一个 skill 只要 name 和 description 就能跑(见第一篇)。但要让它在真实工作里靠得住、又不把 context 占满,有四个进阶技巧值得花十分钟搞懂。
| 技巧 | 解决什么 |
|---|---|
| 全套 metadata 字段 | 除了必填两项,还能限定工具、指定模型 |
| 把 description 写准 | 让 skill 在你期待的时候真的触发 |
| allowed-tools 限权 | 给只读/安全敏感场景上保险,AI 改不了文件 |
| 渐进式披露 + 脚本 | 大 skill 拆成多文件,按需加载,省 context |
逐个看。
一、metadata 字段:两个必填,两个可选
SKILL.md 顶部 frontmatter 支持这几个字段:
| 字段 | 必填? | 作用 | 限制 |
|---|---|---|---|
name | ✅ | skill 的标识 | 只能小写字母、数字、连字符;最长 64 字符;最好和文件夹同名 |
description | ✅ | 告诉 AI 什么时候用它 | 最长 1024 字符;最重要,匹配全靠它 |
allowed-tools | ⬜ | 限制激活时能用哪些工具 | 不写=不限制 |
model | ⬜ | 指定用哪个 Claude 模型 | —— |
记住一句:description 是这里面分量最重的字段,下面单独讲。
二、description 怎么写才触发得准
想象有人对你说”你的工作是帮忙处理文档”——你根本不知道该干嘛。AI 也一样。
一个好的 description 回答两个问题:
- 这个 skill 做什么?(What)
- 什么时候该用它?(When)
如果你的 skill 该触发的时候没触发,通常是 description 没覆盖到你实际说话的方式。补救办法:把你平时会用的措辞、关键词加进去。AI 拿你的话和 description 比意思(上一篇讲过的语义匹配),你描述里的用词越贴近你真实的问法,匹配越稳。
三、allowed-tools:给 skill 上”只读保险”
有时候你想要一个只能读、不能改的 skill——比如安全敏感的流程、只读的排查任务、任何你想加护栏的场景。
---
name: codebase-onboarding
description: Helps new developers understand how the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---这里 allowed-tools 设成了 Read, Grep, Glob, Bash。这个 skill 激活期间,AI 只能用这几个工具——清单外的(改文件、写文件)它一概用不了。
如果你完全不写 allowed-tools,就是不加限制,AI 走它平常的权限规则。
对 vibe-coder 来说这是个被低估的安全开关:你让 AI “带我熟悉一下这个项目”时,根本不希望它顺手改了什么。
allowed-tools把这种”只看不动”的意图变成硬约束。
四、一个大 skill 的文件夹长什么样
skill 不只是一个 SKILL.md,它是一个文件夹。规模大了,标准的组织方式是这样:
my-skill/
├── SKILL.md ← 必须有。主说明书:目录 + 核心指令
├── references/ ← 详细文档(用时才读)
├── scripts/ ← 可执行脚本(让 AI 跑,不是读)
└── assets/ ← 图片、模板、数据文件
只有 SKILL.md 是必须的,其余三个文件夹按需要才加。
为什么要拆?因为 skill 激活时,SKILL.md 的内容会被读进 context,和你的对话共享同一块空间。把两千行全塞进一个文件,既占地方又难维护。
解决办法叫渐进式披露(progressive disclosure):核心指令留在 SKILL.md,详细参考资料拆到单独文件,用到时 AI 才去读。比如你在 SKILL.md 里写一句”涉及系统设计时,去读 references/architecture-guide.md”——那么只有当有人问架构,这个文件才被加载;问”组件放哪”时它根本不会读进来。
这和上一篇那个操作手册的比方是同一回事:context 里放的是一份目录,不是整本书。
经验法则:SKILL.md 控制在 500 行以内。 超了就该考虑拆 reference 文件了。
五、脚本:让 AI”跑”它,别让它”读”
scripts/ 里的脚本有个关键特性:AI 执行它,但不把它的内容读进 context。脚本跑完,只有输出消耗 token。
所以你在 SKILL.md 里要明确写:让 Claude 去”运行”这个脚本,而不是”阅读”它。
什么时候特别有用:
- 环境校验(检查依赖、配置齐不齐)
- 需要每次都一致的数据转换
- 那些”写成测试过的代码”比”让 AI 每次现生成”更可靠的操作
把这类活儿固化成脚本,AI 调用它得到稳定结果,还不占 context——比每次让 AI 重新生成一遍代码强得多。
别自己手写:用 skill-creator 建,建完一定验证加载
讲了这么多字段和结构,但你不用记着手写。
Claude 自己就带一个 skill-creator 的 skill。你直接说”帮我建一个做 XX 的 skill”,它会用 skill-creator 把文件夹、SKILL.md、frontmatter 帮你搭好,该拆文件的拆文件。你只要把”这件事该怎么做”讲清楚。
但有一步绝不能省:建完一定要验证它真的被加载出来了。
为什么?回顾上一篇——name 和 description 是 Claude 启动那一刻读进去的。你刚建的新 skill,当前这个会话还看不到。所以:
- 重启 Claude(改了或新建 skill 都必须重启,这是上一篇的硬规矩)。
- 重启后确认它出现在可用 skill 列表里(用
/skills看一眼,或直接用一句话试着触发它,看它认不认)。
别建完就假设它能用了——很多”我写的 skill 怎么不生效”的困惑,根源就是这一步没做:要么没重启,要么 description 没匹配上。
给 vibe-coder 的话
这一篇的四个技巧,本质都在回答同一个问题:怎么让 skill 既强又不拖累 AI。
- 字段让你精确控制(用哪个模型、能动哪些工具);
allowed-tools让你加护栏(只读,不怕它手滑);- 渐进式披露和脚本让你省 context(目录常驻、正文按需、脚本只跑不读)。
而真正省心的做法是:别把这些当成要背的语法。把意图讲清楚,让 skill-creator 替你落地,然后重启 + 验证。你的精力该花在”我希望 AI 怎么做这件事”,而不是 frontmatter 的拼写上。
会写 skill 之后,最后一个问题是:什么时候不该用 skill?下一篇把它和 CLAUDE.md、斜杠命令、subagent、hook、MCP 摆在一起对比:一张表选对工具。