EP01. "Agent Skills 完整教程：从零写一个 Skill 到团队怎么分享"

首页 › AI 工具 › Claude · Developer and Platform · Agent Skills · EP01

约 18 分钟· #EP01#Claude#Agent Skills

Overview 系列 EP02 已经提过 Skills 是什么、怎么建一个；官方这门 Introduction to Agent Skills 课（6 节课，约 1 小时）把同一件事讲得更细——SKILL.md 具体该怎么配置、多文件 Skill 该怎么组织、Skills 跟 CLAUDE.md / Subagent / Hooks 到底该怎么选、团队怎么分享、出问题怎么排查，这篇笔记聚焦在这些官方课新增的细节上，不重复 Overview EP02 已经讲过的基础
判断原则很直接：「同一件事已经跟 Claude 解释第二遍了」，那就是一个等着被写成 skill 的机会
前置知识：用过 Claude Code 的基本操作，知道 CLAUDE.md 是什么

重点内容

Skill 到底是什么，「按需加载」为什么重要

Skill 是一个带 SKILL.md 文件的目录，YAML frontmatter（至少要有 name 和 description）加上具体的执行指令。

关键机制：Claude Code 启动时只加载所有 skill 的 name 和 description，不会占用完整的上下文窗口。用户发出请求时，Claude 拿这些 description 做语义匹配，匹配上某个 skill 后，会先跟用户确认，确认后才真正去读那份完整的 SKILL.md 内容。

两个存放位置：

类型	路径	特点
Personal（个人）	`~/.claude/skills`（Windows：`C:/Users/<你的用户名>/.claude/skills`）	跟着用户走，所有项目都能用；适合放个人偏好（比如自己习惯的 commit message 格式）
Project（项目）	仓库根目录下的 `.claude/skills`	跟着代码一起进版本控制，团队成员自动共享；适合放团队标准（品牌指南、约定俗成的规则）

跟其他自定义方式的加载/触发差异：

方式	加载时机	触发方式
CLAUDE.md	每次对话都加载	一直生效
Skills	匹配到相关请求才加载	自动（语义匹配相关时）
Slash commands	不主动加载	用户明确打指令才触发

什么时候该写一个 skill：code review 标准、commit message 格式偏好、品牌指南与组织规范、文档模板、某个框架专属的排错 checklist。

动手写第一个 Skill

建目录：

mkdir -p ~/.claude/skills/pr-description

SKILL.md 范例：

---
name: pr-description
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request.
---

When writing a PR description:

1. Run `git diff main...HEAD` to see all changes on this branch
2. Write a description following this format:

## What
One sentence explaining what this PR does.

## Why
Brief context on why this change is needed

## Changes
- Bullet points of specific changes made
- Group related changes together
- Mention any files deleted or renamed

name 用来标识这个 skill；description 决定 Claude 什么时候会把用户的请求匹配到它。

📌 改完一定要重启 Claude Code——新建、修改、删除 skill 之后都要重启才会生效，这是官方课反复强调的一点。

测试方式：重启后先在 skills 清单里确认它出现了，再实际换个分支跑一次请求（比如「帮我这次改动写个 PR 描述」），看会不会真的触发。

匹配全流程：只加载 name+description → 用户发请求时做语义比对 → 匹配上先跟用户确认 → 确认后才读取完整 SKILL.md。

同名冲突时的优先级：Enterprise（企业级）> Personal（个人）> Project（项目）> Plugins（插件）。

进阶配置：四个 frontmatter 字段

字段	是否必选	规则
`name`	必选	只能用小写字母/数字/连字符，最长 64 字符，建议跟目录名保持一致
`description`	必选	最长 1024 字符，决定 Claude 什么时候会用到这个 skill
`allowed-tools`	可选	限制这个 skill 激活时 Claude 能用哪些工具
`model`	可选	指定用哪个 Claude 模型版本执行

写好 description 要答到两个问题：这个 skill 做什么？什么时候该用它？模糊的描述对人和对 AI 都没用——要把用户实际会讲的关键词塞进去，不是写一堆抽象术语。

allowed-tools 范例：

---
name: codebase-onboarding
description: Helps new developers understand the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

配置后，这个 skill 激活时 Claude 只能用列出的工具，不用额外申请其他权限；不写这个字段，就是不设限制。

多文件 Skill：渐进式加载（Progressive Disclosure）

不要把所有内容都硬塞进一份 SKILL.md，按用途拆成几个子目录：

scripts/——可执行代码
references/——额外的参考文档
assets/——图片、模板、数据文件

SKILL.md 里链接过去，并写清楚「什么情况该去读/跑哪个文件」。经验值：SKILL.md 本身控制在 500 行以内。Claude 只有真正需要时才会去读这些支持文件，不会一次性占满上下文。

💡 省 token 的关键技巧：脚本被执行时不会把脚本内容读进上下文，只有输出会占 token——SKILL.md 里该教 Claude「去跑」脚本，而不是「去读」脚本内容。这个做法特别适合环境校验、数据转换这类固定、经过测试、可靠的操作。

Skills vs 其他 Claude Code 功能怎么选

Skills vs CLAUDE.md：CLAUDE.md 每次对话都加载、一直生效，适合项目级恒定不变的规范和框架偏好；Skills 按需加载，适合不需要一直占着上下文的专门流程。

Skills vs Subagents：Skills 是把知识加进当前对话；Subagents 在一个独立、隔离的执行环境里单独跑。需要不同工具权限、要委派出去单独做的工作用 Subagent；整个对话过程都用得上的专业知识用 Skill。

Skills vs Hooks：Hooks 是被事件（文件保存、工具调用）自动触发；Skills 是被用户请求驱动、按语义匹配上下文触发。要自动执行的副作用用 Hook；要引导 Claude 怎么思考的知识用 Skill。

📌 完整的设置通常是几种一起用：CLAUDE.md 定规范、Skills 给任务专业知识、Hooks 做自动化、Subagents 做任务委派、MCP server 接外部工具——不要什么都硬塞进 skill 里做，各有各的适用场景。

团队怎么分享 Skill

分享方式	怎么做	适合场景
提交进仓库	放进 `.claude/skills`，跟着 Git 自动共享	团队 coding 规范、项目专属流程
做成 Plugin 分发	在 plugin 项目里建 `skills` 目录，每个 skill 各自一个文件夹 + `SKILL.md`，透过 marketplace 分发	不绑定特定项目、普遍有用的 skill
Enterprise managed settings	管理员在组织级统一部署，优先级最高，支持 `strictKnownMarketplaces` 配置	强制性标准、安全、合规要求
给 Subagent 配 Skill	在自定义 subagent 的 frontmatter 里显式列出 `skills` 字段	让特定 subagent 具备特定专业知识

📌 Subagent 不会自动看到你的 skills——这是常见的误解，要在自定义 subagent 的 frontmatter 里显式列出 skills 字段才行，而且是 subagent 启动时就整批加载，不是按需匹配。另外，内建的 Explorer / Plan / Verify 这几个 agent 完全不支持使用 skill，只有自定义 subagent 才能配。

出问题怎么排查

第一步永远是先跑一次 skills validator 工具——先抓结构性问题，省掉后面瞎猜的功夫。

症状	常见原因	解法
Skill 完全不触发	`description` 写得太模糊，没有用户实际会讲的关键词	对照真实用户措辞改写 description，加入触发短语（例如 "help me profile this"/"make this faster"）
Skill 读不到/清单里不出现	`SKILL.md` 没放在「一个有名字的目录」里（直接丢在 skills 根目录下不算数）、文件名大小写写错	确认目录结构和文件名（必须精确是 `SKILL.md`）；跑 `claude --debug` 看加载报错
触发了却用了不对的 Skill	好几个 skill 的 description 太像，互相打架	把 description 写得更具体、更有区分度
Skill 被同名的另一个 Skill 盖掉	优先级冲突（Enterprise > Personal > Project > Plugins）	改名，或找管理员确认企业端的设置
Plugin 里的 Skill 不出现	缓存或安装问题	清缓存、重启 Claude Code、重新安装 plugin；还是不行就跑 validator 检查 plugin 结构
跑起来报运行时错误	缺依赖包、脚本没有执行权限、路径写法有问题	补齐依赖；给脚本 `chmod +x`；路径统一用正斜杠（Windows 上也一样）

学完你会

✅ 讲得清一个 skill 从「只加载 name/description」到「语义匹配 → 用户确认 → 读取完整内容」的整个流程
✅ 能自己动手建一个基本 skill，写对 frontmatter，知道改完要重启才生效
✅ 用 allowed-tools/model 收紧一个 skill 的权限和执行模型，用 scripts//references/assets 组织超出 500 行的复杂 skill
✅ 遇到新需求能马上判断该用 Skill、CLAUDE.md、Subagent 还是 Hook
✅ 知道怎么把 skill 分享出去（仓库、plugin、enterprise），以及怎么让自定义 subagent 用上它
✅ Skill 不生效时，知道从 validator 开始排查，而不是瞎猜乱改

常见错误

❌ description 写得很笼统（比如「处理 PR 相关的事」）——Claude 靠语义比对 description 来决定要不要触发这个 skill，写太模糊等于永远匹配不上，要塞进用户实际会讲的关键词
❌ 改完 SKILL.md 不重启 Claude Code 就以为立刻生效——新建、修改、删除 skill 都要重启才会刷新
❌ 所有内容都塞进同一份 SKILL.md，越写越长——超过 500 行该考虑拆成 scripts//references//assets/，SKILL.md 本身只留骨架和指路说明
❌ 让脚本内容整份读进上下文，而不是直接执行——SKILL.md 该教 Claude「去跑」脚本，只有输出占 token，读脚本内容白白浪费上下文
❌ 以为自定义 Subagent 自动能用到所有已建好的 skills——要在 subagent 的 frontmatter 显式列出 skills 字段，而且内建的 Explorer/Plan/Verify 这几个 agent 完全不支持用 skill
💡 Skill 不管用先别急着改指令逻辑，第一步永远是跑一次 skills validator，结构性问题往往比想象中更常见

Sources

官方文档：

Introduction to Agent Skills（课程总览）— https://academy.claude.com/courses/introduction-to-agent-skills
What are skills? — https://academy.claude.com/courses/introduction-to-agent-skills/what-are-skills
Creating your first skill — https://academy.claude.com/courses/introduction-to-agent-skills/creating-your-first-skill
Configuration and multi-file skills — https://academy.claude.com/courses/introduction-to-agent-skills/configuration-and-multi-file-skills
Skills vs. other Claude Code features — https://academy.claude.com/courses/introduction-to-agent-skills/skills-vs-other-claude-code-features
Sharing skills — https://academy.claude.com/courses/introduction-to-agent-skills/sharing-skills
Troubleshooting skills — https://academy.claude.com/courses/introduction-to-agent-skills/troubleshooting-skills