// 做 skill（Claude Code 技能）相关的工作时进入——从零写一个新 skill、调优已有 skill、把反复使用的流程沉淀成 skill、或者在 skill 不触发 / 乱触发时修 description。也能读自己的文件优化自己。用户说"帮我写个 skill / 做个技能 / 优化 skill / 调 description / 这个 skill 不触发 / skill-master 优化下自己 / 把这段流程做成 skill"时都进来。
| name | skill-master |
| description | 做 skill（Claude Code 技能）相关的工作时进入——从零写一个新 skill、调优已有 skill、把反复使用的流程沉淀成 skill、或者在 skill 不触发 / 乱触发时修 description。也能读自己的文件优化自己。用户说"帮我写个 skill / 做个技能 / 优化 skill / 调 description / 这个 skill 不触发 / skill-master 优化下自己 / 把这段流程做成 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 只会被加载一次——它作为一条消息进来之后就一直留着，不会随着对话重读。所以里面要写的是"整段任务期间都成立的原则"，不是"这一步做完就扔掉的步骤"。
---
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`` 预先喂给它，省一轮工具调用。
问用户（每一条都要明确）：
disable-model-invocation: true，只让用户手动 / 触发。用户答完了重复一遍，让他确认。不要边猜边写。
<name>/
├── SKILL.md # 必须
└── reference/ # 可选，SKILL.md 超过 400 行再拆
└── <topic>.md
Skill 第一版尽量只有 SKILL.md。拆文件是为了给"正文里不想塞但又想让 Claude 需要时能查到的东西"找地方，太早拆只是增加理解成本。
description 是 Claude 判断要不要加载你的唯一依据。写错它，skill 再好也等于没有。
结构建议：<做什么> + <什么时候用>。把最典型、用户最可能的触发语原话塞进去——Claude 的匹配是语义的，但原话命中率更高。
反例：
"Helps with code review" ← 太抽象，任何写代码的场景都可能触发，也可能都不触发"Code review assistant" ← 把自己介绍得像个产品，不是说明什么时候该用正例：
"用户想对 PR 或代码改动做 code review 时进入——读 diff、点出问题、给出修改建议。常见触发：'帮我 review 下这个 PR'、'看看我这次改动有没有问题'、'我改完了你扫一眼'。"要点：
默认目标：300 行以内，500 行是上限。超过了要么内容真的需要，要么该拆 reference/ 了。
结构模板（不是必须照抄，是思考顺序）：
reference/xxx.md 里有什么、什么时候去翻写作风格的几条硬要求：
加 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 里。
写完之后至少做一次：
大多数问题在这一步会暴露。发现问题改，改完再跑。
交付时说清楚：skill 装在哪（路径）、怎么触发（用户原话的哪一类 / 或 /<name>）、有没有副作用、下一步怎么迭代（跑一段时间后回来调）。不要长篇总结正文——他能打开看。
用户带着"这个 skill 有问题"来，先别急着改，先搞清楚是哪一类问题。
| 症状 | 大概率原因 | 改哪里 |
|---|---|---|
| 该触发的时候没触发 | description 没覆盖用户真实说法 | 改 description，加用户原话 |
| 不该触发的时候触发了 | description 太泛，或关键词和别的场景重叠 | 改 description，加边界说明或明确排除 |
| 触发了但行为不对 | 正文指令模糊、或者缺关键步骤、或者有矛盾 | 改正文 |
| 跑得特别慢 / 吃特别多 token | 正文太长、或者让 Claude 现写本该是脚本的事 | 拆 reference/ 或加 scripts/ |
| 多轮对话里 skill 好像"失效了" | 大概率没失效，只是被别的上下文盖过。见 §3.5 | 加强 description，或改成正文里用"原则式"语言 |
"NEVER skip step 3" → "第 3 步如果跳过，X 会因为 Y 而失败"。Claude 理解原因之后在边界情况下判断更准拆完了记得在 SKILL.md 留指路句，不要让 Claude 不知道这些文件存在。
一次会话里 skill 只加载一次，加载进来之后不会重读。所以用户说"后面几轮它没照着 skill 做"——内容其实还在，只是 Claude 选了别的路径。改法：
这是一个特殊分支——用户说"skill-master 自己优化下"或"你来改自己"时走这条路。
你现在要改的文件就是你刚读进上下文的这份 SKILL.md 及同目录文件。改完之后当前会话里你还是按旧版本跑——skill 内容不会在同会话重读。所以改完告诉用户"下次会话生效"。
${CLAUDE_SKILL_DIR} 下的 SKILL.md、reference/、scripts/，全读一遍。别凭记忆改，你当前上下文里的那份可能已经被压缩过用户说"帮我看一下这个 skill 逻辑恰不恰当"、"自洽检查"、"通读一下"、"读着别扭"、"顺一下"——指向的都是同一件事：让整份 skill 文档作为一个系统读起来不别扭。
下面 5 条维度同时成立才算过：
怎么做这次检查：
通读整份 SKILL.md（必要时连 reference 一起），按上面 5 条逐条扫，违反点按下面三档分级输出，每条都标位置（行号或节标题）：
列完让用户选改哪些，不要直接动手。
何时主动触发：
!command`` 语法Vue 组件/Composable 重构的决策陪练——用户贴一段代码或指到一个 SFC，skill 先做一次诊断（"胖主干"/"UI和IO纠缠"/"响应式和业务纠缠"），再从三张处方里选一张，逐条给出具体的 extract 步骤序列（先动哪个变量、编译器会报什么错、怎么逐个消掉、何时可回滚）。全程靠编译器绿灯 + 单步可回滚保证行为等价，不依赖测试防护网。触发场景：用户说"这个 Vue 组件太胖 / 想把逻辑抽出来 / 拆一下这个 SFC / 这个 composable 太杂 / 抽个 composable / 拆成 humble / 纯函数化"、或指到一个明显过长的 .vue / composable 文件要求"重构 / 优化 / 拆分"。只管 Vue（Vue 2 Options、Vue 2/3 `<script setup>`、composable、pinia store）。不处理：加新功能（走 feature 流程）、修 bug（走 issue 流程）、跨模块架构重划、后端代码。
写任何目的是让读者记住、跟风、或做点什么的东西时触发——广告文案、产品标题、slogan、发布会讲稿、产品推广页、融资路演、公众号开头、短视频开头、GitHub README（推广向的）、标题党、朋友圈首句。关键判断：写出来的东西成不成，看读者脑子里能不能留下一句能原样说出来的话，并且觉得自己想变成那句话里的人——不看读者懂了什么事实。不适用于技术文档、教程、API 参考、解释型随笔、写给 AI 的指令——那些场合的目的是让读者真正建立理解，用这里讲的手法会翻车。
尤雨溪（Evan You）思维框架。基于 6 个维度、40+ 一手来源的深度调研，提炼出 5 个心智模型、8 条决策启发式、完整表达 DNA。触发词：尤雨溪 / Evan You / 框架设计 / 工具链哲学 / 开源决策 / Vue / Vite / progressive framework
Use when the user wants design judgment in the style of Jonathan Ive, including product simplification, hardware-software coherence, material/process trade-offs, and craft-led decision making. Triggers: Jonathan Ive, Jony Ive, Apple design language, simplify this product, hardware software integration, design process culture, thinness vs usability.
讨论如何管理自己的任务、注意力、时间、精力时触发——事情太多不知道先做哪个、清单永远做不完、拖延重要的事、一天下来感觉什么都没做成、被紧急的事牵着走、该不该答应新请求、想养成习惯但坚持不下来、效率低下想提升。关键判断：用大师的原则（做减法、辨重要、低门槛启动、系统设计）和用户对话、帮 TA 想清楚该不该做、怎么启动、怎么设计可持续的系统——不是帮 TA 列清单或跟踪进度。不适用于项目管理（给别人分任务）、时间记账、产品 roadmap、应急救火。
写任何目的是让另一个脑子建立理解的东西时触发——教程、使用说明、科普、技术博客、README、SKILL.md、给 AI 读的指令文档、解释型随笔、架构说明、onboarding 材料。关键判断：输出要在读者（人或 AI）脑子里建立对某件事的真正理解，而不只是罗列事实或列举规则。写给 AI 的流程指令、skill 内容也适用——把 AI 当聪明的学徒来教而不是当执行引擎来命令，它遇到没覆盖到的情况才能用原则推断。不适用于严格的参考资料（API 字段表、schema 定义、参数列表）。