从零做一个高质量 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，没有 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、一遍没有，把 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 与 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())设为必需。
• 两个同等重要的检查：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，用一两句当场礼貌关闭。
• SLA 定为 48 小时内首次分诊(不是完成 review)，README 公开承诺 7 天回复；每周一个不超过 90 分钟的固定 triage 窗口；stale 机器人取 30 天 stale、14 天关闭(别抄 k8s 的 90 天，skill 生命周期太短)。

度量要区分虚荣指标和有信息量的指标。主判据是有 skill 与无 skill 的 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。