| name | skill-master |
| description | 做 skill（Claude Code 技能）相关的工作时进入——从零写一个新 skill、调优已有 skill、把反复使用的流程沉淀成 skill、或者在 skill 不触发 / 乱触发时修 description。也能读自己的文件优化自己。用户说"帮我写个 skill / 做个技能 / 优化 skill / 调 description / 这个 skill 不触发 / skill-master 优化下自己 / 把这段流程做成 skill"时都进来。 |
skill-master
0. 读完这一节你要做什么
先搞清楚用户现在处于三种场景里的哪一种，然后跳到对应小节：
- 要做一个新的 skill → 读 §2 "创建新 skill"
- 已有 skill 要改（描述不触发、行为不对、该拆文件了） → 读 §3 "优化已有 skill"
- 用户让你优化 skill-master 自己 → 读 §4 "自我优化"
如果判断不出来，就问一句。不要靠猜。
§1 是 skill 的心智模型，任何分支都要熟，但不用每次都重新读——只在你对某个概念把不准时回来翻。
1. 心智模型：一个 skill 到底是什么
一个 skill 是 <skill-name>/SKILL.md，外加同目录下的可选辅助文件。Claude Code 启动时把所有 skill 的名字 + description 收进上下文，Claude 读到用户问题后自己决定要不要拉某个 skill 的正文进来。用户也可以 /skill-name 直接触发。
关键是"渐进加载"——description 始终在上下文（贵），SKILL.md 正文只在触发时进来（触发才花钱），辅助文件只在 SKILL.md 里提到、Claude 判断要看时才读（几乎免费，直到要用）。所以写 skill 最贵的是 description 的每个字，最便宜的是 reference/ 里面的长文。这决定了怎么分配内容：description 像广告语，正文像说明书首页，reference 像附录。
一次会话里一个 skill 只会被加载一次——它作为一条消息进来之后就一直留着，不会随着对话重读。所以里面要写的是"整段任务期间都成立的原则"，不是"这一步做完就扔掉的步骤"。
SKILL.md 的构造
---
name: my-skill # 小写、连字符、<=64 字符；不写就用目录名
description: 一句话说清楚做什么 + 什么时候用 # 关键字段
---
正文（Markdown）
frontmatter 里实际会用到的字段（其他的用到再查 reference/anatomy.md）：
| 字段 | 什么时候写 |
|---|
description | 永远写。Claude 靠这个决定要不要拉你进来 |
when_to_use | description 塞不下更多触发语时用，和 description 拼起来共享 1536 字符上限 |
argument-hint | skill 需要参数时，给用户看 autocomplete 提示 |
disable-model-invocation: true | 只想让用户手动 / 调用（有副作用的 deploy、commit 之类） |
user-invocable: false | 只想让 Claude 后台自动用，不想出现在 / 菜单（背景知识类） |
allowed-tools | 某几个工具不想每次都弹权限问 |
context: fork + agent | 任务独立、不需要看主会话历史，派到子 agent 跑 |
paths | 只在编辑匹配文件时才自动触发（packages/api/**/*.ts 这种） |
安放位置
| 层级 | 路径 | 谁能用 |
|---|
| 用户级 | ~/.claude/skills/<name>/ | 这台机器所有项目 |
| 项目级 | <project>/.claude/skills/<name>/ | 这个仓库 |
| Plugin | <plugin>/skills/<name>/ | 装了这个插件的地方 |
同名时 enterprise > 用户 > 项目。写 skill 前先问用户装哪一层——通用工具放用户级，只和某个项目相关的约定放项目级。
字符替换
$ARGUMENTS（全部入参）、$0/$1/...（位置参数）、${CLAUDE_SKILL_DIR}（skill 自己的目录，引用同目录脚本时用）、${CLAUDE_SESSION_ID}。
两个预处理语法
- 行内
!`gh pr diff`：在 skill 正文送给 Claude 之前执行这个 shell，结果替换掉占位符。这是预处理，不是让 Claude 执行。用来把动态数据（PR 差异、环境信息、当前分支）拼进 prompt。
- 多行
! ``` 代码块：上面的多行版本。
如果你看见自己写的 skill 一上来就让 Claude "先运行 xxx 命令看一下"，停一下——通常应该改成 !xxx`` 预先喂给它，省一轮工具调用。
2. 创建新 skill
2.1 先把意图钉死
问用户（每一条都要明确）：
- 这个 skill 让 Claude 做什么事？ 一句话回答——如果描述不出来，要么需求还不清楚，要么其实是多个 skill。
- 什么时候该触发？ 让用户给 3-5 条真实场景的原话，比如"我想做 X"、"帮我 Y"。这是 description 的原材料。
- 什么时候不该触发？ 找 2-3 条相邻但不该触发的情况。skill 越强大，"别乱触发"越重要。
- 装哪一层？ 用户级还是项目级。不清楚就默认项目级。
- 有没有副作用？ 比如会 push、会发消息、会改共享资源。如果有，默认
disable-model-invocation: true，只让用户手动 / 触发。
用户答完了重复一遍，让他确认。不要边猜边写。
2.2 起骨架
<name>/
├── SKILL.md # 必须
└── reference/ # 可选，SKILL.md 超过 400 行再拆
└── <topic>.md
Skill 第一版尽量只有 SKILL.md。拆文件是为了给"正文里不想塞但又想让 Claude 需要时能查到的东西"找地方，太早拆只是增加理解成本。
2.3 写 description——这是整个 skill 最重要的一行
description 是 Claude 判断要不要加载你的唯一依据。写错它，skill 再好也等于没有。
结构建议：<做什么> + <什么时候用>。把最典型、用户最可能的触发语原话塞进去——Claude 的匹配是语义的，但原话命中率更高。
反例：
"Helps with code review" ← 太抽象，任何写代码的场景都可能触发，也可能都不触发"Code review assistant" ← 把自己介绍得像个产品，不是说明什么时候该用
正例：
"用户想对 PR 或代码改动做 code review 时进入——读 diff、点出问题、给出修改建议。常见触发：'帮我 review 下这个 PR'、'看看我这次改动有没有问题'、'我改完了你扫一眼'。"
要点：
- 用动词开头描述动作，别用名词短语当介绍
- 列 2-4 条具体触发语（用户真实会说的话，不是官样描述）
- 如果它和别的 skill 容易混，在 description 里明确边界（"要做 X 的时候用别的，这个只管 Y"）
- 别怕"推一点"——Claude 的默认倾向是少触发 skill，不是多触发。如果这个 skill 确实在某个场景下有用，就写明确，别含糊
- 全部（description + when_to_use）合起来会被截到 1536 字符，所以把关键触发语放前面
2.4 写正文
默认目标：300 行以内，500 行是上限。超过了要么内容真的需要，要么该拆 reference/ 了。
结构模板（不是必须照抄，是思考顺序）：
- 这个 skill 什么时候该读哪一段——如果正文里有分支（"新建场景走 A，优化场景走 B"），在最上面给个分发指引，Claude 不用每次都把整篇读完
- 心智模型 / 背景——解释"为什么这么做"，不是"怎么做"。Claude 很聪明，给理由比给 MUST 管用
- 工作流 / 步骤——真正的指令。用命令式（"读 X"、"问用户 Y"），不是宾语缺失的被动语态
- 参考文件指路——
reference/xxx.md 里有什么、什么时候去翻
写作风格的几条硬要求：
- 少用全大写 MUST / NEVER。看到自己写这种词停一下，问：能不能改成解释原因的一句话。能的话就改。只有"跳过这步会真的导致错误"的场合才保留硬性语气
- 解释为什么。"做这一步是因为 X"比"必须做这一步"更能迁移到边界情况
- 别过度具体化。skill 是要被用成千上万次的，只围着某 3 个示例打转写出来的指令对真实世界没用。如果只能想出针对具体例子的规则，那就先别写，等 eval 暴露问题再补
- 别加冗余"如果 X 就做 Y"。那种每种情况都穷举的列表 Claude 不会真按它跑，反而会让正文膨胀。把核心原则讲透就行
2.5 什么时候加辅助文件
加 reference/<topic>.md：某类参考材料（API 规格、长表格、详细规则）正文吃不下，但又要让 Claude 需要时能查。写法：在 SKILL.md 里一句话指路——"要查完整字段列表见 [reference/fields.md]"。
加 scripts/<xxx>.py：任务里有确定性的、重复的计算或转换（扫目录、拼 HTML、跑数据清洗）。写一次比让 Claude 每次都现写强——Claude 每次写的版本不一样，又费 token。用 ${CLAUDE_SKILL_DIR}/scripts/xxx.py 引用。
加 assets/<xxx>：模板、示例文件、图片素材。
判断标准：如果某段内容只有 20% 的调用会用到，它就该在辅助文件里，不在 SKILL.md 里。
2.6 自测——最低限度
写完之后至少做一次：
- 读一遍 description，假装你就是读到用户问题的 Claude，问自己"我会拉这个 skill 吗"
- 跑一个真实触发场景，看 Claude 实际的行为和你预期是否一致
- 跑一个不该触发的场景，看会不会误触发
- 通读整份 SKILL.md 做一次自洽检查（标准见 §5），把违反点列出来给用户
大多数问题在这一步会暴露。发现问题改，改完再跑。
2.7 告诉用户
交付时说清楚：skill 装在哪（路径）、怎么触发（用户原话的哪一类 / 或 /<name>）、有没有副作用、下一步怎么迭代（跑一段时间后回来调）。不要长篇总结正文——他能打开看。
3. 优化已有 skill
用户带着"这个 skill 有问题"来，先别急着改，先搞清楚是哪一类问题。
3.1 分类
| 症状 | 大概率原因 | 改哪里 |
|---|
| 该触发的时候没触发 | description 没覆盖用户真实说法 | 改 description，加用户原话 |
| 不该触发的时候触发了 | description 太泛，或关键词和别的场景重叠 | 改 description，加边界说明或明确排除 |
| 触发了但行为不对 | 正文指令模糊、或者缺关键步骤、或者有矛盾 | 改正文 |
| 跑得特别慢 / 吃特别多 token | 正文太长、或者让 Claude 现写本该是脚本的事 | 拆 reference/ 或加 scripts/ |
| 多轮对话里 skill 好像"失效了" | 大概率没失效，只是被别的上下文盖过。见 §3.5 | 加强 description，或改成正文里用"原则式"语言 |
3.2 改 description 的典型操作
- 加触发语：问用户最近一次想用它但没触发时说了什么原话，塞进 description
- 加排除：description 末尾加一句"
（不要和 X 搞混——X 用另一个 skill 处理）"
- 缩短：如果超过 1536 字符会被截，把最关键的触发条件前置
3.3 改正文的典型操作
- 删冗余：读一遍，每一段问"拿掉这段会怎样？"——如果答案是"没怎样"或"Claude 也会做对"，就删
- 把 MUST/NEVER 改成解释：
"NEVER skip step 3" → "第 3 步如果跳过，X 会因为 Y 而失败"。Claude 理解原因之后在边界情况下判断更准
- 把具体例子上升为原则：如果发现只有针对某几个具体案例的规则，想一下它们共同的底层原则是什么，用原则替换
3.4 什么时候该拆文件
- SKILL.md 逼近 500 行
- 正文里有明显的"A 情况 / B 情况"大段分叉，而单次调用只会走其中一个
- 有大段参考材料（表格、字段列表、示例集）正文其实不需要，只是怕 Claude 找不到
拆完了记得在 SKILL.md 留指路句，不要让 Claude 不知道这些文件存在。
3.5 "skill 失效了" 其实不是失效
一次会话里 skill 只加载一次，加载进来之后不会重读。所以用户说"后面几轮它没照着 skill 做"——内容其实还在，只是 Claude 选了别的路径。改法：
- 在正文加强"什么时候该回到 skill 的原则"的表述
- 把"步骤式"指令改成"原则式"指令——原则在整段对话里都成立，步骤只在当下那一轮成立
- 实在不行用 hooks 硬性保证某些行为
4. 自我优化（skill-master 改自己）
这是一个特殊分支——用户说"skill-master 自己优化下"或"你来改自己"时走这条路。
4.1 前提意识
你现在要改的文件就是你刚读进上下文的这份 SKILL.md 及同目录文件。改完之后当前会话里你还是按旧版本跑——skill 内容不会在同会话重读。所以改完告诉用户"下次会话生效"。
4.2 流程
- 读自己所有文件。
${CLAUDE_SKILL_DIR} 下的 SKILL.md、reference/、scripts/，全读一遍。别凭记忆改，你当前上下文里的那份可能已经被压缩过
- 让用户说清楚不满在哪。"哪次调用觉得不对？说了什么、希望是怎样？"——没有具体场景就别动，瞎改只会更糟
- 按 §3 的分类法归因：是 description 问题、正文问题还是文件组织问题
- 提出改动方案先讲。别直接改——你是 skill-master，改自己是高权重操作，让用户确认方案再动手
- 改完自陈改了什么、为什么。一两句话就够
4.3 自我优化的反模式
- 扩大 scope——用户只是抱怨 description 不触发，你顺便把正文也重写了。别这样，改需要最小化
- 加更多规则——遇到一个边界情况就加一条 MUST。规则会膨胀，理解成本越来越高。优先改底层解释、不是加补丁
- 放弃心智模型——skill-master 的价值来自它对 skill 的原理性理解。每次自我优化都要保住 §1 的清晰度，别让它退化成一堆 checklist
5. 自洽检查（review skill 的统一标准）
用户说"帮我看一下这个 skill 逻辑恰不恰当"、"自洽检查"、"通读一下"、"读着别扭"、"顺一下"——指向的都是同一件事：让整份 skill 文档作为一个系统读起来不别扭。
下面 5 条维度同时成立才算过：
- 前后一致：同一个概念在不同地方用同一个名字、归到同一个位置；同一条规则在不同地方说出来意思不变。不出现"A 处说放第 1 节、B 处说放第 3 节"这种矛盾，也不出现"上面叫'目标文件状况'、下面叫'着陆区'"这种术语漂移。
- 完备无空洞：读者能想到的边角情况都有交代。读到一条规则不会在心里嘀咕"那 X 情况怎么办"——要么明说处理方式，要么明说"这种情况这里不管"。退出条件里出现的要求，正文或 reference 里要有出处，不能空降。
- 比例恰当：重要的说得重、有理由；次要的说得轻、不喧宾夺主。不出现"这条为什么这么严 / 这条为什么这么糊"的违和感。一段比另一段多三倍篇幅，应该是因为它真的多三倍重要，不是因为顺手写多了。
- 顺序自然：从上到下读就能建立理解，不需要先跳到后文才能看懂前文，也不需要回头翻才能接住当前这句。每节出现的位置匹配读者此刻已经积累的上下文——心智模型在前，操作流程在中，模板和退出条件在后。
- 无残留疑问：读完任意一段不冒出"这跟刚才那条不是冲突吗"、"这一句怎么突然冒出来"、"这里是不是漏了一步"。
怎么做这次检查：
通读整份 SKILL.md（必要时连 reference 一起），按上面 5 条逐条扫，违反点按下面三档分级输出，每条都标位置（行号或节标题）：
- 必须修——影响理解或会让 AI 走错的硬伤（违反维度 1、2、5 的实质性矛盾或缺失）
- 建议修——读着别扭但还能猜出意思的（多数维度 3、4 问题）
- 不用改但提一下——审美问题或风格选择，留给用户决定
列完让用户选改哪些，不要直接动手。
何时主动触发：
- 用户明示"自洽检查 / 通读 / 顺一下 / 看下逻辑恰不恰当"
- §2.6 自测的最后一步——交付新 skill 前自己跑一次
- §3 优化已有 skill 时，定位问题的第一道扫描就是这个
6. 常见陷阱
- description 写成"这个 skill 能做 X"——描述的是能力不是触发条件。改成"用户想 X 时用"
- 正文塞一堆 MUST/ALWAYS/NEVER——Claude 不是按规则引擎跑的，原因比规矩管用
- 把教程当 skill——如果内容是"怎么在 Vue 里用 X"这种普适教程，它该在用户级 skill 或文档里，不该绑项目
- 一个 skill 想做 3 件事——description 会写不清，触发会出错。拆成多个 skill，或者做一个只负责"路由到哪个子 skill"的入口
- 为了"全面"写一堆不会用到的字段——每个 frontmatter 字段都是认知成本。只写你实际需要的
- 忘了 skill 是要被迁移和分享的——写的时候想想"别人读到这个会懂吗"，而不是"我现在看得懂就行"
7. 参考
官方文档：https://code.claude.com/docs/en/skills
