一个 Skill 就是给 Claude 写的"专业说明书"。说明书上写清了三件事：什么情况下翻开它、翻开了按什么步骤干、干活时有哪些规则和边界。核心文件叫 SKILL.md，分两个部分：头顶的 YAML 配置区和下面的正文指令区。配置决定规则，正文决定流程。下面按 11 项配置，逐项讲清楚每样东西规定了什么、为什么重要。
1. name ------ 身份证
Skill 的唯一标识。必须用英文小写字母和短横线，最长 64 个字符，而且必须和放 skill 的文件夹名字一模一样。它决定了三件事：系统怎么找到它、用户怎么手动调用它（输入斜杠加名字就行）、会不会跟别的 skill 撞名。
2. description ------ 触发开关（最重要）
这是整个 skill 的灵魂，决定 Claude 会不会在合适的时机自动加载你的 skill。原理是这样的：Claude 每次启动时会扫一遍所有 skill 的 name 和 description，装进自己的"能力目录"。一个 skill 约占用 100 个 token 常驻空间。当你提一个任务，Claude 靠语言理解去匹配------这个任务跟哪个 description 说的是同一回事？匹配上了就加载完整说明书，没匹配上就当你没装过这个 skill。这个过程不是关键词匹配、不是正则表达式，而是语义理解，所以有一定概率性------同一个 prompt 在不同 session 下触发结果可能不同。
几个必须知道的关键点：
- description 最长 1024 个字符，但 Claude 主要看前 250 个字符做匹配决策，所以触发关键词一定要前置。
- 系统最多同时管理 30 个 skill，超过的会被静默丢弃，装太多反而有害。
- 写法上必须用第三人称客观陈述（"该 skill 应在用户提到某某场景时使用"），因为 description 是注入系统提示词的，客观指令比对话口吻更容易被准确匹配。
- 还要注意"稍微主动"------把用户可能说出的各种说法（术语、口语、缩写、变体）都列进去，因为 AI 天然有欠触发倾向，宁可范围宽一点也别漏掉。
总结一句话：正文决定 skill 被加载后能不能"做对"，但 description 决定 skill 能不能被"看见"。
3. argument-hint ------ 参数提示牌
如果你的 skill 需要用户传参数，这个字段告诉用户"请传什么"。用户输入斜杠加 skill 名后，自动补全会显示这段提示。它只做提醒，不做任何校验。用人话写清参数名，别写 arg1、arg2 这种没人看得懂的占位符。
4. disable-model-invocation ------ 防 AI 手贱
这是一个安全锁。设为 true 之后，Claude 完全不知道这个 skill 存在------description 不会进入上下文，子代理也不会预加载它。只有用户手动敲命令才能唤醒。什么时候必须加这把锁？所有你不放心让 AI 自己决定执行的操作：部署到生产环境、删除数据库、发版推送、发送消息通知。这些事需要人做最终判断，不能让 AI 替你拍板。
5. user-invocable ------ 控制用户能否手动调
跟上面正好反过来。设为 false 之后，skill 从菜单里消失，用户看不到也调不了------但 Claude 仍能在合适的时候自动加载。适合"后台知识"型 skill。比如团队的编码规范、架构文档、术语约定表------Claude 需要在干活时知道这些内容，但用户没理由去手动执行一个叫"编码规范"的操作。它是一本参考书，不是一个操作按钮。
这两条组合出三种调用模式：
- 默认模式（大家都能触发，什么都不用设）
- 纯手动模式（只有用户能触发，危险操作专用）
- 纯自动模式（只有 AI 能触发，后台知识专用）
注意千万不要两条都禁掉------那样 skill 就彻底废了，不如直接关掉。
6. allowed-tools ------ 工具白名单
Skill 执行期间，这个列表里的工具自动跳过权限弹窗，不需要每次都问用户。这既是为了效率，也是一种安全声明------一个只读 skill 本来就不该有删除权限。还能细化到只允许特定 bash 命令，其他一律不行。没列出的工具不是完全不能用，只是需要用户逐次手动批准。
7. model ------ 选模型
指定这个 skill 用哪个模型来跑。三个选项：haiku 最快最便宜，适合代码格式化这类机械活；sonnet 默认均衡，什么都能干；opus 最强最慢，适合架构审查这类需要深思熟虑的事。一般不用填------切换模型会清空上下文缓存，有额外成本，不是免费午餐。
8. context ------ 隔离运行
设为 fork 之后，skill 在独立子代理中运行，跟主对话完全隔离。好处两个：一是不让 skill 产生的大量输出撑爆主对话上下文；二是给 skill 一张白纸------它看不到你们之前聊了什么，只带着说明书本身去干活。适合代码审计、大规模文件分析这类输出量大又不需要跟你交互的任务。
9. agent ------ 子代理类型
跟上面那条配合使用。不同类型子代理有不同的默认模型和工具权限。Explore 型只有只读工具，适合快速搜索；Plan 型适合先研究再规划；general-purpose 型什么都能干，是默认选择。选对类型，子代理干活更高效。
10. hooks ------ 事件钩子
这不属于 SKILL.md 的字段，而是 skill 目录里的一套独立配置文件。它的作用：在 skill 运行的关键时刻自动插入检查------工具调用前校验参数阻止危险命令、调用后自动格式化或记日志、结束时清理临时文件。
hooks 和 description 触发有本质区别。description 是让 AI 自己判断该不该翻说明书，靠的是智能。hooks 是硬性规则------不管你是谁、怎么想的，到了这一步就必须执行这个检查，靠的是确定性。安全性要求高的场景，应该优先用 hooks 而不是靠 AI 自觉。
11. audit.log ------ 审计日志
这也是通过 hooks 实现的功能。原理很简单：每次工具调用完成后，自动往日志文件里追加一条记录------时间、操作人、用了什么工具。实现方式从最简单的文本追加，到结构化 JSON 日志，再到把日志发送到远程服务器集中管理。出问题时你能回溯每一步操作，团队协作时你知道谁改了什么，需要合规审计时你有完整操作轨迹。唯一需要注意：绝对不要把密码、API key 等敏感信息写进日志，必须做脱敏处理。
一张表总结
| 配置项 | 作用 | 必填/可选 |
|---|---|---|
| name | 叫什么、怎么找到 | 必填 |
| description | 什么时候用，整个 skill 的灵魂 | 必填 |
| argument-hint | 用户要传什么参数 | 可选 |
| disable-model-invocation | 防 AI 自己调用，给危险操作上锁 | 可选 |
| user-invocable | 控制用户能否手动调，给后台知识隐身 | 可选 |
| allowed-tools | 干活时能用哪些工具，权限边界 | 可选 |
| model | 用哪个大脑思考 | 可选 |
| context | 要不要隔离运行 | 可选 |
| agent | 派什么类型的助手干活 | 可选 |
| hooks | 关键节点的安全检查，确定性保障 | 可选 |
| audit.log | 操作留痕，可追溯 | 可选 |
前两项是基本盘，定义了身份和触发条件。中间七项是按需开启的控制开关。最后两项不属于 SKILL.md 本身，但属于 skill 工程质量的一部分------决定了可检查性和可追溯性。
理解了这 11 样东西，你就知道一个 skill 能规定什么、不能规定什么了。