Example：一份九十行的说明书，决定了你写 Skill 的第一印象

你在 Claude Code 里问一句 skill 该怎么写，它大概率会甩给你一个叫 example-skill 的东西。名字起得毫无想象空间，内容更没什么想象空间：一个文件，九十来行，三条 frontmatter，几段骨架说明，完事。

这东西挂在 Smithery 上，署名 anthropics，带官方认证章，安装量 19。19 这个数字摆在那堆动辄几万次安装的 MCP 服务器旁边，基本等于零。它真正的身份藏在仓库路径里：anthropics/claude-plugins-official，往下 plugins/example-plugin/skills/example-skill。四层目录，落到最后一个子目录，里面只有一份 SKILL.md。

那个仓库四万五千多星，挂着二十八个插件目录，是 Anthropic 官方维护的插件集散地。example-skill 在里面最不起眼，却也是最常被复制粘贴的一个。原因不复杂，它是很多人这辈子见到的第一份官方 Skill 样本，长得什么样，后来就照着长。

我的判断是：这份样本值得读，但它值钱的地方和它标榜的地方不一样，而且它已经落后于现行规范好几处。照抄能跑通，但会漏掉三件事，字段版本、上下文成本、还有那个真正决定生死的 description。

使用场景

先说它什么时候会冒头。description 写得非常直白，触发条件全压在“skill 格式”这个语义场上：demonstrate skills、show skill format、create a skill template，外加一句 skill development patterns。你说“帮我看看 skill 该怎么组织”，它会出来。你说“帮我做份 PPT”，它一动不动。

安装一条命令，Smithery 页面直接给的：

npx -y skills add https://smithery.ai/skills/anthropics/example-skill --agent claude-code

--agent 后面能换，主流编码 Agent 基本都在页面上列着，选谁就装到谁的目录里：

claude-code   cursor     codex      gemini-cli   windsurf
cline         continue   opencode   goose        amp          roo

但我建议先别装。理由很简单：整个 skill 只有一个纯文本文件，GitHub raw 链接一开就能读完。装它的收益是多一份上下文，成本是多一个永远在抢触发机会的 skill。对一个纯说明书型的文件，读比装划算。

还有一层时效问题得交代。Smithery 在页面顶部挂了公告：MCP Proxy 和托管身份在 10 月 31 日关停，run.tools 和 server.smithery.ai 上的服务地址、Smithery API、账号体系当天失效，站点本身保留为公开的 MCP registry。上面那条命令走的是 skills CLI 读 registry，理论上不受影响；真装不上，直接从 GitHub 取 raw 文件，内容一模一样。

装进去之后它做什么？什么也不做。没有脚本，没有 API 调用，没有文件处理。它只在你问格式的时候把骨架念一遍：必填文件是哪个，可选目录有哪些，frontmatter 有哪几个字段，description 该怎么写。就这些。

技术架构与设计决策

说是架构，其实是一份最小契约。整个 skill 目录里只有一份 SKILL.md，没有 references/，没有 scripts/，没有 assets/。而它自己在讲可选支持文件时列了四个目录，一个都没用上。这个反差本身就是信号：它在演示形状，不在演示能力。

往上退一层看插件。plugins/example-plugin 一共七个文件：插件元数据、MCP 配置、许可证和 README，外加一个 legacy 命令 md 和两份 SKILL.md。

plugin.json 的描述值得停一下。原文写的是 demonstrating all Claude Code extension options including commands, agents, skills, hooks, and MCP servers，五类扩展点。我把整个目录翻了一遍，实际落地的只有三类，commands、skills、.mcp.json。agents/ 和 hooks/ 这两个目录压根不存在。这算不上什么大错，但一个自称演示全部扩展点的样板房少了两个房间，你照着它找 hooks 怎么写，只会找不到。

.mcp.json 也是同一个路数。里面对着 https://mcp.example.com/api 配了一个 http 类型的 server，占位域名，解析不了。所以 MCP 那一格同样是形状，跑起来连不上。

真正算设计决策的只有一条，但很关键：skill 是 model-invoked。你不能运行它，没有斜杠入口（那是 user-invoked 那套的活），它靠上下文匹配被模型自己选中。文件里把这件事说得很清楚，skill 是模型自主调用的能力，command 是用户主动触发的，agent 是 Claude 派生出来的。三者不是同一类东西，很多人混着讲。

第二条决策更有用，藏得更深：同一份内容，两种目录形状。skills/<name>/SKILL.md 和 commands/<name>.md 的加载行为完全一致，差别只有文件布局。README 里明说 commands/ 是 legacy 格式，新插件应该走 skills/。插件里两个 example-command 并存，就是为了让你亲眼看见这件事。这条信息现在很有价值，因为一堆老教程还在教 commands/。

frontmatter 只用了三个字段：name、description、version。前两个必填，第三个官方标成可选。整个机制就压在这三行上：name 和 description 会常驻在所有会话的上下文里，模型靠它们判断这次要不要用这个 skill。正文只在被选中之后才加载。

这套东西叫 progressive disclosure，也是这份文件最大的空白。它讲了目录可以放什么，一个字没讲为什么。为什么 references/ 要拆开、为什么正文要短、为什么不把所有资料糊进主文件，全部留白。规范那边写得很硬：元数据大约 100 tokens 常驻启动，SKILL.md 正文建议 5000 tokens 以内，resources 按需加载，主文件控制在 500 行内。不知道这个成本结构的人，会把十页文档全塞进 SKILL.md，然后纳闷为什么 skill 一多模型就开始犯傻。

洞察与反思

拿它跟现行规范逐条对，能对出五处具体偏差。规范原文在 agentskills.io/specification，字段表和长度约束写得相当细。

第一行最要紧。规范里根本没有 version 这个一级字段，版本号要写进 metadata 下面，格式是 metadata.version。example-skill 把它抬成一级字段，写上去不报错，但跨 Agent 移植时它什么都不保证，因为规范里没这个键，别的实现认不认全看运气。

allowed-tools 是第二个坑。example-skill 用 YAML 数组写法，规范要求空格分隔的字符串，而且支持参数级限制，Bash(git:*) 这种只开放 git 子命令。数组写法在 Claude Code 里能认，换到别的实现就未必。规范自己还专门标了 experimental，跨实现支持度本来就不统一。

第三个偏差是缺项。可选字段里只有 version 被示范，license、compatibility、metadata 一个都没提。而 compatibility 恰恰是跨 Agent 移植时最有用的那格。

它写的是系统包依赖、网络需求和目标产品。多 Agent 生态走到今天，这一格的重要性比 2025 年底写这份文件时高得多，而这份样本一个字都没示范。

目录约定也对不上。规范给的三个约定目录是 scripts/、references/、assets/，example-skill 写的是 references/examples/scripts/。examples/ 不在规范里，示例文件按约定应该进 assets/。单看这不影响运行，但它会传染，别人照着写，就会长出一批各走各路的目录。

再说 description。规范的要求是同时讲清 what 和 when，并带上能帮模型识别任务的关键词，长度 1 到 1024 字符。example-skill 的写法是压倒性的 when：一句 This skill should be used when the user asks to 打头，挂四个具体触发短语，末尾补一句 what。这是 Claude Code 的实际风格，也是这份文件里唯一真正值钱的示范。

为什么值钱，因为它是唯一能直接影响成败的字段。元数据常驻上下文，模型先拿它做初筛，筛不中，你后面写三千字也没人看。不少 skill 写得又长又认真却从来不触发，问题九成出在 description：要么全是 when 没有 what，要么关键词太抽象，模型判断不了相关性。

还有个数字挺说明问题。仓库四万五千多星，这份子目录在 Smithery 上的安装量是 19。星是给整个目录的，19 是给这一个文件的。悬殊到这个程度只能说明一件事，大家来读，不装。对一个纯说明书型 skill，这恰恰是对的用法，它不需要被触发，它需要被引用。

局限也得讲清，三处留白都不小：

• 测试。全文关于验证只有一句 Test that the skill activates for expected queries，怎么测、测什么、失败怎么调，没讲
• 拆分。什么内容留在主文件，什么下沉到 references/，判定标准是什么，全靠 progressive disclosure 那段自己悟
• 权重。多个 skill 的 description 撞在一起怎么办，只留一句 Avoid overlap with other skills 的触发条件，然后没了

真实项目里，最后这一条恰恰是最难的部分。

资源地址

总结

该不该用它，取决于你要的是哪一样。想要一份不会写错字段名的最小骨架，它够用，结构照抄、description 的句式照搬，十几分钟就能写出第一个能跑的 skill。

想要一份能长期维护的 skill，它就不够了。字段对着 agentskills.io 核一遍，version 挪进 metadata，allowed-tools 改成空格分隔字符串，把 compatibility 补上，再按 100 tokens 常驻、5000 tokens 正文、资源按需加载这套成本结构决定哪些内容留在主文件。

回头看，这份九十行文件最好的地方不是它写了什么，而是它存在本身。它把“skill 只是一个带 frontmatter 的 Markdown 文件”这件事钉死了，没有构建、没有依赖、没有运行时。这个门槛低得离谱，才是 Agent Skills 这套东西能扩散开的真正原因。至于那五处过期的细节，把它当 2025 年 11 月的快照读，别当规范读。