skill-master

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 先把意图钉死

问用户（每一条都要明确）：

1. 这个 skill 让 Claude 做什么事？ 一句话回答——如果描述不出来，要么需求还不清楚，要么其实是多个 skill。
2. 什么时候该触发？ 让用户给 3-5 条真实场景的原话，比如"我想做 X"、"帮我 Y"。这是 description 的原材料。
3. 什么时候不该触发？ 找 2-3 条相邻但不该触发的情况。skill 越强大，"别乱触发"越重要。
4. 装哪一层？ 用户级还是项目级。不清楚就默认项目级。
5. 有没有副作用？ 比如会 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/ 了。

结构模板（不是必须照抄，是思考顺序）：

1. 这个 skill 什么时候该读哪一段——如果正文里有分支（"新建场景走 A，优化场景走 B"），在最上面给个分发指引，Claude 不用每次都把整篇读完
2. 心智模型 / 背景——解释"为什么这么做"，不是"怎么做"。Claude 很聪明，给理由比给 MUST 管用
3. 工作流 / 步骤——真正的指令。用命令式（"读 X"、"问用户 Y"），不是宾语缺失的被动语态
4. 参考文件指路——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 自测——最低限度

写完之后至少做一次：

1. 读一遍 description，假装你就是读到用户问题的 Claude，问自己"我会拉这个 skill 吗"
2. 跑一个真实触发场景，看 Claude 实际的行为和你预期是否一致
3. 跑一个不该触发的场景，看会不会误触发
4. 通读整份 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 流程

1. 读自己所有文件。${CLAUDE_SKILL_DIR} 下的 SKILL.md、reference/、scripts/，全读一遍。别凭记忆改，你当前上下文里的那份可能已经被压缩过
2. 让用户说清楚不满在哪。"哪次调用觉得不对？说了什么、希望是怎样？"——没有具体场景就别动，瞎改只会更糟
3. 按 §3 的分类法归因：是 description 问题、正文问题还是文件组织问题
4. 提出改动方案先讲。别直接改——你是 skill-master，改自己是高权重操作，让用户确认方案再动手
5. 改完自陈改了什么、为什么。一两句话就够

4.3 自我优化的反模式

• 扩大 scope——用户只是抱怨 description 不触发，你顺便把正文也重写了。别这样，改需要最小化
• 加更多规则——遇到一个边界情况就加一条 MUST。规则会膨胀，理解成本越来越高。优先改底层解释、不是加补丁
• 放弃心智模型——skill-master 的价值来自它对 skill 的原理性理解。每次自我优化都要保住 §1 的清晰度，别让它退化成一堆 checklist

---

5. 自洽检查（review skill 的统一标准）

用户说"帮我看一下这个 skill 逻辑恰不恰当"、"自洽检查"、"通读一下"、"读着别扭"、"顺一下"——指向的都是同一件事：让整份 skill 文档作为一个系统读起来不别扭。

下面 5 条维度同时成立才算过：

1. 前后一致：同一个概念在不同地方用同一个名字、归到同一个位置；同一条规则在不同地方说出来意思不变。不出现"A 处说放第 1 节、B 处说放第 3 节"这种矛盾，也不出现"上面叫'目标文件状况'、下面叫'着陆区'"这种术语漂移。
2. 完备无空洞：读者能想到的边角情况都有交代。读到一条规则不会在心里嘀咕"那 X 情况怎么办"——要么明说处理方式，要么明说"这种情况这里不管"。退出条件里出现的要求，正文或 reference 里要有出处，不能空降。
3. 比例恰当：重要的说得重、有理由；次要的说得轻、不喧宾夺主。不出现"这条为什么这么严 / 这条为什么这么糊"的违和感。一段比另一段多三倍篇幅，应该是因为它真的多三倍重要，不是因为顺手写多了。
4. 顺序自然：从上到下读就能建立理解，不需要先跳到后文才能看懂前文，也不需要回头翻才能接住当前这句。每节出现的位置匹配读者此刻已经积累的上下文——心智模型在前，操作流程在中，模板和退出条件在后。
5. 无残留疑问：读完任意一段不冒出"这跟刚才那条不是冲突吗"、"这一句怎么突然冒出来"、"这里是不是漏了一步"。

怎么做这次检查：

通读整份 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. 参考

• reference/anatomy.md——frontmatter 全字段速查、字符替换、lifecycle 细节、!command`` 语法
• reference/techniques.md——description 调优模式、progressive disclosure 的实际案例、bundled scripts 的写法、subagent / context fork 什么时候用

官方文档：https://code.claude.com/docs/en/skills