从四十个技能
到一个技能库

00摘要：九条论断

下面每一条都可以被证伪，也可以被一条命令复核。如果只读这一页，你应该记住第 1 条和第 2 条—— 它们解释了为什么大多数技能库建完之后毫无动静。

01判定：什么才该做成技能

技能库最常见的浪费不是写错了，是写了一批本来不该写成技能的东西。 一个技能封装的是「这件事该怎么做才对」的判断；如果它是固定操作、是一次性任务、 或者需要实时数据，做成技能只是让简单的事情多绕一圈。

四类产物的分野

「让模型做某事」有四种载体，它们的适用边界比多数人以为的窄。选错载体的代价不是效率降低， 而是后续维护成本被永久抬高——因为技能会进入每一次会话的上下文，脚本不会。

02三层契约：哪一层才是承重墙

五个官方仓库看起来完全不同：目录层级不同、清单格式不同、索引结构不同。 但把它们拆成「技能 / 分发包 / 展示索引」三层之后，会发现只有一个层被全部五家共享， 而另外两层各自只在自家生态内有效。

为什么 L1 是承重墙

因为 name 和 description 同时承担两个职责：发现（机器解析出这是什么） 和 触发（模型判断此刻该不该用）。这两个职责被压进同一段文本， 于是格式约束与写作质量必须同时满足——这是技能格式最不寻常的地方。

对比之下，一张 REST API 的 servers 字段只影响路由，不影响语义。 技能没有这种奢侈：它的元数据既是索引键，又是提示词。

03五仓库对照：差异都发生在包装层

把五家官方仓库摊开对比，会发现它们真正的分歧只有一个：用什么维度把技能分组。 主题、品类、信任等级、品牌、展示标签——五种不同的分组哲学，但每个 SKILL.md 的内部结构一模一样。

五种分组哲学没有优劣，因为它们的约束不同：Anthropic 要解决「一次装一组相关能力」， Google 要解决「几百个技能怎么浏览」，OpenAI 要解决「哪些能自动装、哪些必须用户确认」。 你的约束决定你的分组维度，而分组维度只影响 L2。

发现机制有两条路

vercel 的文档把发现规则写得很直白，值得抄：CLI 会在约 60 个「容器目录」 （skills/、.claude/skills/、.codebuddy/skills/ 等）里找 SKILL.md， 往下最多走三层；更浅的位置会遮蔽更深的位置。

但还有第二条路：如果根目录存在 .claude-plugin/marketplace.json， 清单里声明的技能路径会被直接采用，不受三层限制。 两条路殊途同归——所以清单里写的必须是真实路径，否则等于给所有人埋了一个安装失败。

04六步法：从意图到可安装

这套流程不是五个仓库里任何一家的原文，而是从它们的共同约束反推出来的最小完备集。 每一步都有可检验的完成判据——没有判据的步骤，等于没有这一步。

S3　分层披露：技能库能扩展的唯一原因

规范把加载拆成三级：元数据（约 100 tokens，全量技能常驻）、 正文（建议 <5000 tokens，触发时才载入）、资源（按需读取，可无限）。 这不是性能优化，而是技能库规模的物理上限——如果所有内容都必须常驻， 你的库就不可能超过十几个技能。

因此「500 行」不是风格建议，是预算。正文里最该被移出去的是这三类：

• 参考数据——字段表、枚举值、术语表。它们不是每次都需要，但每次都在占位置。
• 分支说明——同一技能支持多个变体（如三家云厂商），按变体拆成独立引用文件，模型只读需要的那一个。
• 可执行的东西——任何你会在每次任务里重新写一遍的小脚本。它在 scripts/ 里执行时不进上下文，写进正文则每次都要读。

- [字段规范](references/spec.md) — 需要核对长度、字符集、
  保留词时读；正常写作流程不需要

S4　评测：没有对照，就无法判断技能是帮忙还是添乱

官方 skill-creator 的核心循环只有一句话：在测试提示上跑「带技能」和「不带技能」两个版本， 然后对比。这不是学术洁癖——技能最典型的失败不是「不生效」，而是生效了但把结果带偏， 而后者只有在对照下才看得见。

测试集要写成真实用户会说的话，不是需求文档的措辞。这是我自己那份的写法：

{
  "skill_name": "skill-authoring",
  "evals": [
    {
      "id": 1,
      "prompt": "我写了个技能，但装了之后基本不触发，怎么改？",
      "expected_output": "先诊断 description：长度是否在 150-600、
                        是否有 Use when 子句、是否只讲了 what 没讲 when。
                        给出改写版本。不要一上来就改正文。"
    },
    {
      "id": 3,
      "prompt": "这个 SKILL.md 有 900 行，要不要拆",
      "expected_output": "建议拆分：正文超 500 行会与任务争抢上下文。
                        提出 references/ 分解方案，每个文件带「何时读」，
                        命令式步骤留在正文。"
    }
  ]
}

expected_output 写的是「应该发生什么」，不是「应该输出什么文本」—— 前者能容纳不同的合理表达，后者会把评测变成字符串比对。

05描述工程：唯一常驻的那个字段

如果只能改一个地方来提高技能库的命中率，改 description。 它既是索引键又是提示词，在每次会话开始时就进入上下文——技能是否被想起，全看这几十个字。

为什么「做什么」不够

模型在选择技能时做的不是「能力匹配」，而是「场景匹配」。 一个写着「简历评估与岗位匹配技能」的描述，只回答了「这个工具能干什么」， 却没有回答「我现在这个处境该不该用它」。前者是产品说明书，后者才是触发器。

Anthropic 在官方的技能创作指南里直接承认了这件事：模型存在触发不足的倾向， 所以描述应当写得比你觉得自然的样子更主动一点。Google 则用另一种方式解决同一个问题—— 在描述末尾固定加一句 Don't use for …，用排除法划定边界。

三段式

长度区间与后果

四个真实改法

下面四组都来自实测审计，左列是原文，右列是同一技能的改写。 注意改写没有增加任何新能力，只是把「何时用」补回去。

中文作者特有的坑

官方示例清一色英文，直接照抄会漏掉一件事：触发是按字面匹配的。 如果描述只有英文 Use when the user mentions dashboards， 而用户用中文说「做个看板」，这个技能就不会被想起。

解法是把中英两套说法都塞进描述，且中文要写用户真的会打的字，不是术语： 「看板 / 仪表盘 / 数据大屏」三个词都要出现，因为用户会用其中任意一个。 这一条无法从任何官方文档里学到——它只在中文语境下暴露。

06上下文税：技能库真正的成本

每个技能的元数据都会进入每一次会话，无论它是否被触发。这是一笔固定支出， 而多数人建库时只算「我多了什么能力」，不算「我每天为此付出什么」。

三层预算，三种付费方

这个结构的副产品是一个反直觉的结论：技能库的质量由「删掉了多少」决定，而不是「收进了多少」。 一个有 20 个精准触发技能的库，比一个有 200 个模糊技能的库更能帮上忙—— 不仅因为噪声少，还因为前者给任务留了 94% 的上下文。

修剪判据

每隔一段时间对着技能库问三个问题，答案是否定就删：

• 过去一个月，它被调用过吗？（没有 → 它不是技能，是一个愿望）
• 它解决的问题，模型自己已经会了吗？（会 → 它只是复述）
• 它的输出，和不用它时真的有区别吗？（没区别 → 参见论断 08）

07审计实测：四十五个技能的真实病灶

方法论讲完之后，需要一次真实的体检。下面是拿一套 18 条规则的检查器， 对一个真实技能库（45 个技能）跑出的结果——每条结论都可以用一条命令复现。

三个读得出来的结论

一、公开分发的门槛被低估了

37 个技能没有 license 字段。这是最容易补、也最容易被忽略的一项： 缺了它，别人即使拿到代码也无法合法复用。对个人库无所谓，对公开仓库是硬伤—— 而且它是一次性决定，补一次永久有效，性价比在所有规则里最高。

二、真正影响生效的是描述，不是正文

14 个描述完全不含触发信号，13 个短于 150 字符，合计 27 次命中——覆盖了近六成技能。 这些技能的正文可能写得很好，但它们从不在正确的时刻被想起。 这也解释了为什么「加了很多技能但感觉没变化」：不是技能没用，是它们没被调用。

三、手工清点必然漏

最初我用一级目录遍历数出 44 个技能。换成递归扫描后发现是 45 个—— 多出来的三个藏在三层嵌套里（playwright-cli 及其两个兄弟技能）。 它们不报错、不显眼、也从未被算进任何统计。 这就是为什么审计必须是工具而不是人工：漏掉的从来不是最显眼的那个。

python3 tools/lint.py --path ~/.workbuddy/skills --json

08工具链：把规范变成闸门

规范写在网页上，就只是建议；写进检查器，才成为约束。这一章给出四个零依赖工具的设计与规则集， 它们的作用不是替代判断，而是让「低级的、机械的、必然反复犯的」错误不再需要判断。

为什么坚持零依赖

三个理由，按重要性排：CI 上能跑（GitHub runner 只有裸 python3，装 PyYAML 要多一步且可能失败）； 别人的机器上能跑（你的技能库要被别人 clone，不该先要求他配环境）； 十年后还能跑（依赖会腐烂，标准库不会）。

代价是要自己写一个 YAML frontmatter 解析器。好在技能格式的 frontmatter 只用到极小的 YAML 子集： 顶层标量、块标量（| 与 >）、一层嵌套（metadata）。 约 60 行代码就够，而且永远不会因为上游库改 API 而失效。

规则集

刻意区分「阻断」与「警告」是这套规则集的关键设计。如果 18 条全部阻断，人们会开始加 --no-verify；如果全部警告，等于什么都没说。

CI 闸门

两道就够了，都很便宜：契约仍然成立，索引没有过期。

name: skills
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python3 tools/lint.py --quiet
      - run: python3 tools/build_index.py --check

09反模式清单

按「内容 / 结构 / 治理」三层归拢十四条。每条都给出症状、成因和修正动作—— 症状是你能观察到的现象，成因才是需要改的地方。

内容层：技能本身写得不对

结构层：库的形状不对

治理层：库的生命周期没人管

10路线图：先修哪一处

存量改造不应该按「文件顺序」推进，而应该按「收益 / 成本比」排。 下面五步的顺序是刻意打乱的——不是从易到难，而是从最能改变生效率的开始。

每步的验收标准

不建议一次性打包全库。迁移的价值在于逐步暴露问题——把 45 个技能一次全搬进新仓库， 等于把 45 个未知状态一次性冻结，之后每一次改动都要先搞清楚「这个是当初为什么这么写的」。 搬一个，验一个。

11结论

以下是我的判断，不是共识。它们建立在前面可复跑的证据上，但推论本身包含取舍。

12参考来源

按证据类型分组。所有一手来源均在 2026 年 11 月实际抓取核对。

规范与一手文档

• Agent Skills Specification — agentskills.io/specification：字段定义、长度限制、渐进披露、命名规则
• anthropics/skills — 仓库结构、.claude-plugin/marketplace.json 实例、skill-creator 的方法论原文
• google/skills — index.json 生成式索引、skills/<品类>/<name> 两级布局、描述中的排除式子句
• openai/skills — .curated/.system/.experimental 信任分层；该仓库已标注 deprecated，官方指向 openai/plugins
• MiniMax-AI/skills — 单 plugin 全量打包、三端 INSTALL.md 适配
• vercel-labs/agent-skills — 发现规则（容器目录、三层上限、浅覆盖深）、skills.sh.json 展示分组

一手实测（可复跑）

• 45 个技能的全量审计：python3 tools/lint.py --path <技能库> --json，得 64 错误 / 48 警告
• 目录深度差异：一级遍历得 44 个，递归扫描得 45 个，差额来自三层嵌套
• 检查器自检：首次运行抓出自身引用缺失

推导与建模（非实测，需谨慎引用）

• 图 4 的上下文占用率为建模估算：以规范建议的单技能约 100 tokens 乘技能数，除以 32k 窗口。实际值随描述长度与分词器浮动，不同模型窗口也不同。
• 「500 行」来自规范的建议值（<5000 tokens），折算关系随语言与排版变化，中文正文的 token 密度通常高于英文。
• 图 5 的「影响 27 个技能」为去重后的粗略口径，一个技能可同时命中多条规则。

本文档自身

• 单文件 HTML，零外部依赖，不引任何 CDN
• 全部图表为手写 SVG，无图表库
• 配色遵循三级文字色阶（对比度均 ≥3.0）与语义色分层（色块用原色、文字用深色版）