skill-development：一份教你造技能本身的技能说明书

你大概率见过各种 “XX 技能使用指南”，但 Anthropic 在 Smithery 上架的 skill-development 反了个向。它不教你用某个技能，而是教你造技能。准确说，是给 Claude Code 插件写那种能塞进仓库、被自动发现、随插件分发的可复用能力包。

我一开始以为这又是一份 “最佳实践罗列”，翻两页就能看完。读完才明白它真正值钱的是一套关于上下文预算的思考。技能不是文档，技能是给模型装的一套程序性记忆。装得对，通用代理一夜变成领域专家；装错了，就是仓库里多了一坨没人触发的 Markdown。

这份技能把 “怎么造” 拆得相当工程化。它先定义技能的 Anatomy（解剖结构），再用渐进式披露（progressive disclosure）讲清楚什么该常驻上下文、什么该按需加载。这两块合起来，才是它区别于普通 README 的地方，也是我打算重点拆的部分。

它面向的不是随手写段提示词的临时需求，而是打算长期维护、跨环境复用、甚至分发给团队的能力建设。如果你正琢磨怎么把团队沉淀的领域知识变成别人装上就能用的东西，这份技能基本就是标准答案。

架构解析

一个技能的最小形态只有 SKILL.md。YAML frontmatter 里 name 和 description 是硬要求，正文是 Markdown 指令。就这三样，技能就能被 Claude Code 识别并触发。可选的是 bundled resources，也就是 scripts/、references/、assets/ 三件套，按需要挂。

三类捆绑资源分工明确，别混着用。

渐进式披露是这套设计的灵魂。它把内容切成三级：第一级是元数据，name 加 description，约一百词，永远待在上下文里，决定技能会不会被触发；第二级是 SKILL.md 正文，技能被触发时才加载，控制在五千词以内；第三级是捆绑资源，模型按需取用，脚本还能直接执行、不占上下文。

我以前一直觉得 “把说明写全” 才是好技能，能多写一句是一句。看了这套分层才反应过来，上下文是稀缺资源。让一百词的触发描述常驻，比把八千词操作手册全塞进上下文聪明太多。模型先把 “该不该接这个活” 判断完，再决定要不要读细节，这才是省算力的正确顺序。

工作流分析

造一个技能不是打开文件写说明就完事。这份技能给了一条六步流水线：先理解技能要解决的真实用例，再规划哪些内容该做成可复用资源，然后建目录骨架，接着写 SKILL.md，最后验证、测试、迭代。流程不短，但每一步都在防返工。

前两步容易被人跳过，恰恰最该慢。理解阶段要拿具体用例说话，用户原话或生成示例都行，别一口气问太多问题把人问烦。规划阶段要逐一审视每个用例，判断它到底需要脚本、参考文档还是资产文件。这步想不清楚，后面写出来的技能要么臃肿要么缺胳膊少腿。

最反直觉的是第四步的写法建议。它要求你 “把另一个 Claude 实例当成用户” 来写。意思是 SKILL.md 不是给你看的，是给模型看的。正文用命令式（imperative），说 “要创建 hook，先定义事件类型”，而不是 “你应该先定义事件类型”。frontmatter 的 description 必须用第三人称，还要塞进具体触发短语。

验证环节也有讲究。它不直接让你自查，而是建议用 skill-reviewer 代理去审。结构对不对、frontmatter 有没有触发短语、写作是不是第二人称、内容有没有冗余，对着清单逐条过。本地还能用 cc --plugin-dir /path/to/plugin 把插件加载起来真跑一遍，比肉眼读 Markdown 靠谱得多。

使用场景

这份技能最适合两类人。一类是插件作者，要把团队沉淀的领域知识打包成可分发能力；另一类是维护大型 skill 库的人，需要一套统一标准避免每个技能长得都不一样。它的规则基本是给 “规模化生产技能” 准备的，零散写一两个技能反而显得规矩重。

触发它的最佳时机也很明确：用户说 “帮我建个技能”、“给插件加个技能”、“改进这段技能描述” 的时候。描述写得好不好，直接决定技能会不会被召唤。文档里点名了三种烂描述：用错人称、太模糊、或者直接没有触发短语。这三类我都在真实仓库里见过。

我得说句不中听的。很多人写 description 像写功能简介，“Provides hook guidance” 这种话模型看了也不知道什么时候该用。正确写法是把用户原话搬进去：“This skill should be used when the user asks to ‘create a hook’…”。触发短语不是装饰，是技能的入口，入口写歪了里面再对也白搭。

洞察与反思

这套规范里我最服气的一点是它对 “大文件” 的处理。references 里的文档超过一万词怎么办？它说别硬塞，给模型提供 grep 模式让它自己定位。这等于承认：上下文不是图书馆，是工作台，东西要现用现取，而不是全部摊开。

但也有让我皱眉的地方。它把 SKILL.md 正文限制在五千词以内，对大多数技能够用，可遇到真复杂的领域（比如一整套 CI 流水线编排），五千词未必讲得透。这时候就得靠 references 拆，结构会变复杂，对新手不算友好，等于把门槛转移到了组织能力上。

横向看，这套设计和 Cursor 的 Rules、GitHub Copilot 的 prompt 文件是同一思路的不同实现。区别在 Claude Code 把技能做成了 “可分发、可组合” 的一等公民。你写的技能能随插件装到别人环境里，这是它比单文件 prompt 走得更远、也更接近软件工程的地方。

对技能作者来说，真正要记住的就一句话：先想清楚什么时候该触发，再想里面写什么。大多数烂技能不是内容错，是入口糊。把 description 当 API 的路由条件来设计，技能才算真正接入了模型的决策回路，否则它只是安静躺在 skills/ 目录里的一堆文字。

资源地址

总结

skill-development 的价值不在那些写作细则，而在它把 “造技能” 当成工程问题来对待。三层渐进式披露是核心，触发描述的质量是命门。照它做，你能造出被模型真正用起来的技能，而不是仓库里好看的文档。

它不适合想快速糊一个临时提示词的人。如果你只想要一段一次性的指令，直接写 prompt 更省事。但凡是打算长期维护、跨环境复用、甚至分发给团队的能力，这套方法论值得照抄，尤其是它对上下文预算的那种克制。

最后留个开放问题：当技能数量涨到几百个，靠一百词的描述做路由还会准吗？Anthropic 现在把判断权交给了模型，未来会不会需要一套技能之间的检索或层级机制，这事儿值得持续盯着。