从零做一个高质量 Agent Skill,并把它当开源项目运营

先给总纲:一个高质量 skill 要同时赢两场。造出来是「让模型在装了几十个 skill 的环境里,靠一行描述可靠地选中你」;运营起来是「让陌生人在一个中位安装数为 1 的货架上找到并信任你」。两场的胜负手都不在你以为的地方——不在正文写得多精巧,而在触发面的字节预算,和分发货架的策展逻辑。

一、先认清「规范 vs Claude Code」这条分叉

这是最底层的一刀,后面所有决策都建在它上面【稳】。Agent Skills 有一份跨厂商开放规范(agentskills.io),Cursor、Gemini CLI、VS Code Copilot、OpenAI Codex 等 40+ 工具都在实现它;而 Claude Code 在规范之上有一大堆私有扩展。两者的字段集不一样,写错就掉进「本地能跑、发出去别人用不了」的坑。

可移植的 frontmatter 是一个仅 6 键的白名单:

Claude Code 私有多出约 14 个字段(when_to_use、paths、context、model、hooks、disable-model-invocation…),全部不在白名单里。两个参考校验器(Anthropic 的 quick_validate.py、agentskills 的 skills-ref)对多余键都直接报 Unexpected key(s)。

最容易踩的一个错:把 Claude Code 私有字段塞进 metadata: 求「兼容」。【已收窄】这在机制上无效——CC 从顶层读 context/model 这些键,塞进 metadata 只会让 context: fork 之类静默失效,行为和你文档写的不一致。开源就老实只写 6 键;要给 CC 用户的私有行为,在 README 里给一段可粘贴 patch。

二、description:决定生死的那一行

启动时进上下文的只有每个 skill 的 name + description(CC 还会拼上 when_to_use)。模型要在「可能上百个 skill」里靠这一行做匹配——它是自主触发时的主要匹配文本。这里有三个必须分清的长度预算:

• 规范 / API / claude.ai:硬上限 1024 字符,超了拒绝。
• Claude Code 运行时:description+when_to_use 合并后截断在 1536 字符,超了静默截断。
• 全局 listing 预算 ≈ 上下文窗口的 1%。溢出时不是截断,而是从你「最少调用」的那些 skill 开始,整条丢掉 description、只留 name。

第三条是对开源作者最致命的机制【已收窄】,它构成一个冷启动死循环:用户装了 40 个 skill,你的新 skill 从没被调用过 → 排在第一个被降级成 name-only → 没有 description 可供匹配 → 永远不会自动触发 → 于是永远是「最少调用」。写多长的描述都救不了,因为它整条不在上下文里了。

两个能救的动作:①把最强触发词放在 description 的前 200 字符,即使被砍到只剩前段也能匹配;②在 README 里明确写「首次请用 /your-skill 手动调一次」,把它顶出「最少调用」队列。

怎么写(官方自家 skill 实证)

必须第三人称,但别误读成「只能写名词短语」。Anthropic 最好的 skill 用的是祈使句对 agent 说话——Use this skill whenever the user wants to…。被禁的是作者第一人称和对终端用户说的 You can use this to…(理由:描述被注入 system prompt,人称不一致会伤 discovery)。

长度不是固定区间,是歧义度的函数。实测官方样本 description 字符数中位数 231,不是「一句话」:

• 触发词是排他 token(文件后缀 .pptx、CLI 名、领域术语)→ 写到 900 字符也安全,穷举动词短语 + 扩展名 + 裸关键词列表(pdf skill 437 字符、xlsx ~950)。
• 触发词是公共名词(「data」「report」「analysis」)→ 200 字也会变全局噪音源。

负向边界是可选的第三段,别默认全加。只有当你的仓库里有 ≥2 个语义相邻的 skill、且抢的方向明确时才写 Do NOT trigger when…——因为每个 skill 的 description 都常驻,排除子句对所有请求都收 token 税,这正是 Anthropic 17 个 skill 里只有 4 个用它的原因。

三、SKILL.md 正文:双峰,不是「取中间值」

实测 Anthropic 17 个非模板 SKILL.md,行数是明显的双峰【已收窄】,不是单一目标值,中间 129→236 行是空档:

• 行为约束型 ~32–129 行:每轮都要复现的规范,压短。
• 查询参考型 ~236–541 行:细节拆进 references/,正文只留导航(claude-api skill 甚至 541 行)。

按类型选档,别取中间值。规范里的 <500 行 / <5000 token 是推荐不是硬拒(claude-api skill 自己就 68KB/约 17k token)。但要知道机制:Claude Code 的 auto-compaction 只保留每个 skill 的前 5000 token,所有重挂 skill 共享 25000、从最近调用往回填、老的整份丢掉——所以不可违背的铁律必须写在文件顶部。

语气用「常驻指令」——第二人称祈使、现在时,禁 we'll / let's / in this guide(叙事化流水账的残留)。体裁是「决策表 + 不变量 + 坑清单 + 指路牌」,不是散文:H1 之后第一个元素最好是一张 3–7 行的 | Task | Approach | 路由表(Office 家族惯例),而不是复述 description 的 Overview 段。同一信息,直接给代码 ≈ 50 token,先科普再选型 ≈ 150 token——3 倍开销零增量。(2026-07 注:Claude 5 代的一手口径是「除要害外避免过度约束」——路由表和坑清单保留,禁令收窄到不可违背的少数,见文首更新框。)

四、脚本:不要先验决定「这该写脚本」

最反直觉的一条【稳】:别拍脑袋决定哪块写成脚本。做法是——草稿写完,拿 2–3 条真实用户口吻的 prompt,在同一轮同时开两个 subagent:一个带 skill、一个不带,然后读 transcript,看模型在带 skill 那一臂里仍然自己现写的同一个 helper——那才固化成 scripts/ 里的文件。判断类任务(取舍/命名/版式/语气)永远留给模型。(此法只在 Claude Code 成立;claude.ai 无 subagent,要另写降级流程。)

落地约定:

• 脚本间用文件 + 位置参数对接,不用自然语言、不用 stdin;按 analyze → plan.json → validate → apply → verify 五段切分(官方叫 plan-validate-execute 模式)。中间产物落盘,让模型迭代计划而不碰原件。
• 默认零第三方依赖、只用标准库、用 python3;非要依赖就 PEP 723 内联元数据 + uv run --script,并在 SKILL.md 顶部显式列依赖。
• cwd 无关:禁包相对 import、禁靠当前目录找同级资源,一律 Path(__file__).resolve().parent。
• 写操作默认不可破坏、给 --dry-run、同输入重跑产出字节一致。
• 错误信息 = 「错在哪(含收到的值)+ 合法取值全集」,可选加第三段「下一步跑哪个」,配非零退出码——让模型零额外读取自纠。office/validate.py 的两档退出码(参数错 exit(2) / 校验失败 exit(1) / 通过 0)值得抄。「stdout 即产物」的脚本,错误必须走 stderr,否则会污染下游 JSON。

五、references/:不是加载器契约,是命名习惯

唯一让文件被读到的机制,是 SKILL.md 正文里一条模型愿意照着 Read 的路径字符串【稳】。references/ 这个目录名本身没有任何魔力。推论很硬:

• 路径写错 = 文件死了,而校验器不会报错(某知名插件真出过 19 条死链、活过 5 个 minor 版本没人发现)。规范示例文件名用大写 REFERENCE.md,但仓库实际是小写 reference.md——照文案抄名字会在大小写敏感的 Linux 沙箱里 cat 失败,macOS 上还看不出来。
• 每个 reference 在 SKILL.md 里出现两次:一次在模型做决定的那一行(带触发条件),一次在底部资源索引(带一句摘要)。
• 引用只能一层深——嵌套两层,模型对被引文件可能只 head -100 预览,读到残缺信息;>100 行的 reference 文件头要加目录。
• 判据:一次调用里使用概率 <50% 的内容下沉到 references/;但禁令类内容永远留正文,绝不下沉。这才是渐进式披露的真实经济学:正文是每轮复发的常驻成本,reference 是一次性成本。

六、评测:两份物理分离的文件

触发评测和执行评测必须分开,合成一份就无法定位失败层【稳】:

• 触发评测(该不该被选中):~20 条 query(8–10 正 + 8–10 条 near-miss 负样本),每条跑 3 次取 trigger_rate,阈值 0.5,60/40 train-holdout,按 test 分而不是 train 分选描述。负样本必须是「差一点点」的,否则整套评测无信息量。
• 执行评测(选中之后完成度):同一 prompt 跑两遍(有 skill / 无 skill),把 pass_rate / time / tokens 三个 delta 一起报,并主动删掉「两边都过」的 assertion——不然你在测模型而不是测 skill。

现成工具就一个能打:官方 skill-creator 插件(/plugin install skill-creator@claude-plugins-official),把两类评测、grading、盲测 A/B、HTML 评审页全包了。平台文档里「没有内置评测方式」那句已落后于它。⚠️两个真实坑:目录字母序会让 delta 符号反(把主目录命名 new_skill/ 避开);没有 timing.json 时 tokens 字段会静默变成字符数——所以每个 run 结束的通知要当场落盘 timing。

七、安全:allowed-tools 不是沙箱

最常见的致命误解【已收窄】:allowed-tools 是「本轮免确认授权」,不是能力限制;它在你发下一条消息时就清除。disallowed-tools 也是一轮、且是 Claude Code 专有。没有任何 frontmatter 字段是沙箱。真正的安全边界只有 settings.json 的 permissions.deny(及企业策略)。想让 skill 只读,在 README 给用户一段可粘贴的 deny 配置,别靠 frontmatter。

供应链风险的真实排序(在本机 137 个真实 SKILL.md 上校准):

1. skill 自授 allowed-tools(尤其 Bash(*))+ 捆绑 scripts/ 里的 payload——这才是头号入口。
2. .claude-plugin/plugin.json 让目录带 agents/hooks/.mcp.json 一起加载。
3. hooks: frontmatter。
4. !`cmd` 预处理(渲染阶段、模型看到前就执行)——真实出现率≈0,但一旦出现就是零交互执行。

一次性总闸:~/.claude/settings.json 加 "disableSkillShellExecution": true。核心认知:安装一个 skill,在威胁模型上等同于安装一个可执行软件;发布方的安全责任 = 一份可机读的能力声明 + 一份可复现的审计清单 + 一份针对 prompt injection 的 SECURITY.md。

八、边界:skill / MCP / subagent / command / CLAUDE.md 怎么选

这是选错代价最大的一维。先破除一个过时的心智模型:slash command 已并入 skill——.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都产出 /deploy 且行为相同【已收窄】。所以问题不是「做 skill 还是 command」。判别式:

九、分发与冷启动:最反鸡汤的一维

先看证据【已收窄】:官方目录的安装数是极端幂律——某快照 265 个插件、361 万次安装,top10 占 53.8%,中位数 = 1,52% 的插件恰好只有 1 次安装。而排第一的 frontend-design 是个 41 行 SKILL.md、零脚本的东西。两个结论同时成立:代码量不是头部的条件;光「进了货架」几乎一文不值(头部 8/10 是 Anthropic 自家或大厂)。决定采用的是「被策展 / 品牌」,不是「上架」本身。

可执行的落地:

• 两个货架:claude-plugins-official(Anthropic 全权策展,无申请入口)+ claude-community(可审核、独立开发者真能到,platform.claude.com/plugins/submit 提交,落社区库、按 commit SHA 钉住、每晚同步)。
• 同一个仓库并排放多家 harness 的 manifest = 成本最低的 10 倍分发【稳】。SKILL.md 已是跨 40+ 工具标准,不做等于自愿放弃 90% 货架。
• 要一行安装,仓库根目录得有 .claude-plugin/marketplace.json,把一个仓拆成多个 plugin(Anthropic 自己拆成 document-skills / example-skills / claude-api 三个)。@ 陷阱:/plugin install <plugin>@<name> 里 @ 后是 marketplace.json 顶层 name,不是仓库名——抄错用户得到「not found」,而你自己复现不出来(因为你已经 marketplace add 过了)。从一台没加过你 marketplace 的机器测这两行命令。
• README 首屏:一句「是什么 + 给谁」+ 可粘贴安装 + 可粘贴的触发原话。skill 没有显式调用入口,用户装完不知道该说什么话,就等于装了个坏的。

十、把它当开源项目:仓库、版本、CI

仓库最小可信集

• 没有 LICENSE = 排他版权(别人连合法复制都不行)。LICENSE 和 CODEOWNERS 是仅有的两个不能由 org 级 .github 仓库默认下发的社区文件,必须逐仓放。MIT vs Apache-2.0 的实质差:Apache 多一条明示专利授权(+专利反诉终止),代价是 State-changes 通知和 Trademark 限制两条。
• CONTRIBUTING 建两道分离的门:语法门(vendored 的 ~40 行校验器,别盲依赖自称「demo only」的 skills-ref)+ eval 门(每个 PR 必须带 ≥3 条触发话术 + 预期行为)。后者才是能收敛「品味之争」的那道——它让你能以客观理由拒掉「这只是把 prompt 重述一遍、没有 scripts/references」。
• issue 用 YAML forms 强制采集「客户端 + 版本 + skill 版本 + 触发用的原话 prompt + 是否被激活」——skill 的 bug 九成是「没触发」而非「跑错」,缺原话 100% 不可复现。

版本与发版

SKILL.md 没有 version 字段。真正决定「用户能否收到更新」的是 .claude-plugin/plugin.json 的 version——它是 Claude Code 的更新缓存键,不 bump 等于没发版【稳,CONFIRMED】。内容型 semver 按触发面 + 环境契约定 breaking:description/when_to_use 只能 append,绝不删或收窄触发词(删了静默失效,模型直接不再加载、无报错)。但要清醒:裸 skill 上的 semver 只是沟通约定不是强制(没有渠道解析 semver 范围),版本打在 plugin 层才有真实版本串。git tag 用 {plugin-name}--v{version}(双连字符),裸 v1.2.0 会让依赖你的插件解析失败。

CI(markdown 为主的仓库怎么做有意义的门禁)

• 绝不给「必需状态检查」的 workflow 加 paths: 过滤——被跳过的 job 不上报 check,PR 会永久卡在「Expected」。小仓直接别加 paths,skill CI 就几秒。矩阵变动会反复炸必需检查名,所以只把一个聚合 job(ci-ok,needs:[…] + if: always())设为必需。
• 两个 co-primary 检查:schema 校验(name 正则 / 无保留词 anthropic·claude / 无 XML 标签、description ≤1024、body ≤500 行——决定 skill 能不能加载)+ 引用完整性(lychee --offline + 自写脚本查 SKILL.md 提到的每个路径真实存在)。反向可达性只做 warning(helper 模块会假阳)。
• 选 DCO 不选 CLA:Apache-2.0 第 5 条已把 inbound=outbound 写死;CLA Assistant 要 pull_request_target + 写权限 PAT,正是你在别处极力避开的攻击面。

十一、治理与度量

三条经三视角全票通过【稳,CONFIRMED】:

• PR 分诊建在可复现行为证据上,不是文本 diff:模板强制三件套(触发 prompt 原文 / 改前后 transcript / 是否动了 description),配 needs-evidence 标签 + 14 天自动关。没有这条,队列 100% 会死。
• Scope 控制的默认答案是「不新增 skill 目录」:Non-goals 写死在 README 首屏和 CONTRIBUTING,新 skill 一律引导 fork / 自建 marketplace 而不是 merge,用 1–2 句当场礼貌关闭。
• SLA = 48 小时内首次分诊(不是完成 review),README 公开承诺 7 天回复;每周一个 ≤90 分钟固定 triage 窗口;stale 机器人取 30 天 stale / 14 天关闭(别抄 k8s 的 90 天,skill 生命周期太短)。

度量要区分虚荣和信息量:主判据是 with/without 的 pass_rate delta(不是唯一——tool_calls 开销差、盲评 winner、触发准确度都独立有信息量)。star 与真实使用几乎脱钩;裸 skill 没有下载注册表,常用的四个健康比值只有两个(merged-PR/star、issue 关闭率)能直接算,想要下载数得额外包成 plugin/npm。Release 附件的 download_count 是最干净的装机代理(公开、零 PII、累计不丢)。永远别在 SKILL.md 或脚本里埋 curl 打点——它跑在别人的 agent session 里,这是「同意」问题不是技术问题。

最后一个必然会遇到的现实:AI 生成的 PR 洪水是 skill 仓库的默认结局(Anthropic 自己的 skills 仓 1023 个 PR 只 merge 44、742 个挂着、根目录连 CONTRIBUTING 都没有)。提前装闸门,interaction-limits 当临时限流而非永久关门。

十二、这份研究没能覆盖的

• 2026 年 2–7 月是完全盲区。凡涉及 Claude Code 版本 / 功能名 / 定价、以及 plugin 与 marketplace 那套(不到一年的新面)的结论都可能已变,发布前用当前版本实测。(2026-07-27:上下文工程一块已由官方一手补上,见文首更新框;plugin/marketplace 面仍未覆盖。)
• Anthropic 内部资产不可见。官方是否有 skill 使用遥测、内部评测集、以及 skill 生态的策展逻辑,都无法证实——本文的采用度判断只覆盖公开领域。
• 大量数字是「文档/源码声称」的当前值,不是长期契约。本文抓的是 2026-07-24 的实现;skills-ref 自称「demonstration purposes only」,规范页无版本号,治理已交给社区仓 agentskills/agentskills。引用具体脚本名和目录路径时锁 commit,别当稳定 API。

主要来源(经三视角核验,均抓一手):Agent Skills 开放规范 agentskills.io/specification(6 键 frontmatter 白名单、name/description/compatibility 约束);Anthropic 官方仓库 anthropics/skills 的 skills/skill-creator/scripts/quick_validate.py(ALLOWED_PROPERTIES 集合、尖括号拒绝、名长上限)、skills/pdf|docx|xlsx|pptx/SKILL.md(真实 description 长度与体裁、license: Proprietary)、scripts/office/validate.py(两档退出码)、评测工具链 run_eval.py/run_loop.py/aggregate_benchmark.py;agentskills/agentskills 的 skills-ref/src/skills_ref/validator.py(name==父目录名强制、demonstration-only 声明);Claude Code 官方文档 code.claude.com/docs/en/skills(17 字段 frontmatter 表、1536 字符 listing 截断、1% listing 预算与降级、5000/25000 token 压缩、allowed-tools 一轮授权语义、disableSkillShellExecution、slash command 已并入 skill);platform.claude.com 的 Agent Skills overview 与 best-practices(plan-validate-execute、progressive disclosure、eval 三步、one-level-deep 引用);官方 plugin 目录本机遥测快照(265 插件 / 361 万安装 / 中位数 1 / top10=53.8%);GitHub 社区健康文件文档、choosealicense(MIT vs Apache-2.0 权限表)、Keep a Changelog、CNCF/Node.js 治理文档。共 45 条载重结论进入三视角对抗核验(8 全票 / 37 部分修正 / 0 推翻),本文写的是修正版;分档与时效风险已逐条标注。2026-07-27 增补来源:Thariq(Claude Code 团队)《The new rules of context engineering for Claude 5 models》,x.com/trq212,2026-07-25。