64 / 1024 / 1536 / 500 / 100 / 3——这六个数字里，只有两个是真会拦住你的硬限。分不清哪两个，你会在错的地方省字。
SKILL.md 该写多长、拆几个文件、description 怎么写才触发得准——这些问题，Anthropic 在 Skill authoring best practices 那一页上全给了答案，而且给的是数字。麻烦在于那页有六千多字，读完只记住「要简洁」等于没读。本期把它压成一张速查表，再逐条问「凭什么是这个数」——因为知道机制，你才知道哪条能破、哪条破了就出事。文中点名的每个 skill 与文档都能点开，第 03 节全部用官方仓库里真实跑着的 skill 当范本，第 04 节讲这页文档自己也会坑你的地方。
# ① 拷官方最小骨架（anthropics/skills 的 template/ 下只有这一个文件）
mkdir -p .claude/skills/analyzing-invoices
curl -o .claude/skills/analyzing-invoices/SKILL.md \
https://raw.githubusercontent.com/anthropics/skills/main/template/SKILL.md
# ② 按上面的速查表填 name / description，然后查 YAML 语法（v2.1.233+）
/plugin validate
# ③ 看这条 skill 在列表里占了多少 —— 这就是你付的常驻税
/context
# ④ 想要评估那套机器，装官方的 skill-creator
/plugin install skill-creator@claude-plugins-official
# ⑤ 两周后回头查账：谁从没被触发过（v2.1.252+，需交互式会话）
/skill-doctor
因为它被注入 system prompt。官方原话是：人称不一致会导致「发现问题」（discovery problems）。「Processes Excel files and generates reports」是对的，「I can help you...」「You can use this to...」都不对——system prompt 里突然冒出一个第一人称的自述，模型分不清那是它自己的身份还是一条待选工具。而 description 是唯一的检索键：官方明说 Claude 要靠它「从可能 100+ 个 skill 里选对那一个」。正文写得再好，也进不了这一轮筛选。
官方给了一个非常具体的行为观察：遇到嵌套引用（SKILL.md → advanced.md → details.md）时，Claude 常常不是完整读文件，而是用 head -100 之类的命令先扫个开头，结果拿到的是残缺信息。所以规矩不是「别写太多层」，是「所有 reference 都要从 SKILL.md 直连」。同一个机制还解释了另一条：超过 100 行的 reference 要在开头放目录——因为模型很可能只看得到前 100 行，目录能让它至少知道后面还有什么。
看那张三层表的最后一行：脚本通过 bash 执行，代码本身永远不进上下文，只有输出计费。所以「预置一个 validate.py」和「让模型每次现编一段校验代码」的差别不是风格，是三件事同时改善：更可靠（不会每次编得不一样）、更省 token（代码不进 context）、更快（不用生成）。官方还要求你在指令里写明是执行还是当参考读——「Run analyze_form.py to extract fields」和「See analyze_form.py for the algorithm」是两件事，前者省 token，后者花 token。
官方的比喻是把 Claude 当成一个在路上走的机器人。两侧是悬崖的窄桥——只有一条安全路径，就给死命令加护栏（低自由度），文档给的例子是数据库迁移：「Run exactly this script: python scripts/migrate.py --verify --backup」，后面直接跟一句「不要改这条命令、不要加参数」。空旷无障碍的原野——很多条路都通，就只给方向（高自由度），例子是代码审查：分析结构 → 找 bug 与边界情况 → 提可读性建议 → 核对项目约定，四句话，没有一条具体命令。中间档是「带参数的伪代码或脚本」，用在「有个首选做法、但允许变化」的场景。判据只有一条：任务有多脆弱。
anthropics/skills 里每一种都有实物。照实物抄，比照文档抄准——因为文档里的示例路径，跟真实 skill 并不一致。SKILL.md 只留 quick start，其余全部甩给同级文件：FORMS.md / REFERENCE.md / EXAMPLES.md，Claude 用到哪份读哪份。适合「一件事，但有几个深水区」的 skill。
claude-api文档给的示范是一个 BigQuery skill：reference/finance.md / sales.md / product.md / marketing.md，SKILL.md 只当导航。理由很实在：用户问销售指标时，模型不该被迫读进财务和市场的 schema。官方 claude-api skill 就是这个结构的成品（它随 Claude Code 一起分发），按语言 + 按主题拆成十几份文档。官方甚至建议在 SKILL.md 里直接写好 grep 命令（grep -i "revenue" reference/finance.md），让模型自己去捞。什么时候别用：只有一个域的 skill 硬拆成多文件，只会多一轮读盘。
docx基础内容摆在正文，高级分支挂链接：「简单编辑直接改 XML；要改追踪修订 → 看 REDLINING.md；要 OOXML 细节 → 看 OOXML.md」。而 docx skill 真身里最值得抄的是那个校验闭环——解包、用 scripts/merge_runs.py 合并碎片化的 run、原地改 word/document.xml（并明写「不要重排、不要美化格式」）、重新打包，然后：
python scripts/office/validate.py out.docx --original doc.docx
# XSD 校验；--auto-repair 修常见问题；改了追踪修订还要加 --author注意一个真实的不一致：最佳实践页里那条示例命令写的是 python ooxml/scripts/validate.py unpacked_dir/，而仓库里 skills/docx/SKILL.md 实际用的是 scripts/office/validate.py out.docx --original doc.docx。文档里的路径是教学示意，不是能跑的命令。要抄命令，去抄 skill 本身。
官方文档只说 description 要写「做什么 + 什么时候用」，但看真身——docx 的 description 结尾是：「Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.」负向触发词是文档没讲、实物在用的一招。当你的 skill 库里有好几个功能相邻的 skill（docx / pdf / pptx / xlsx 就是典型），写清楚「不管什么」比再堆一个正向触发词有效得多。
官方把「先建评估」加粗写在评估章节开头，五步是：① 不带 skill 跑真实任务，记下具体失败 → ② 就这些缺口造三个场景 → ③ 量出基线 → ④ 只写刚好够补缺口的字 → ⑤ 跑评估、对照基线、迭代。理由是一句话：这样你解决的才是真问题。
但这里有个坑：官方给了评估的 JSON 结构（skills / query / files / expected_behavior），紧跟着一条 Note 却说——目前没有内置的方式来跑这些评估，要用户自己搭。所以真想按五步走，你要么自己写 runner，要么装 skill-creator（它有自己一套 evals/evals.json → grading.json → benchmark.json 的流程，跑「带 skill / 不带 skill」两组对照）。两条线不通用，别以为写一份到处能跑。
官方推荐的迭代法是开两个实例：Claude A 帮你写和改这个 skill，Claude B 装着它去干真活。你观察 B 哪里翻车，把观察带回给 A。文档给的例子很具体——「我让 B 出区域销售报表，它写了查询但忘了过滤测试账号，skill 里明明提了这条规则，是不是不够显眼？」A 可能的回应是把措辞从 always 改成 MUST，或者调整章节顺序。这套办法的价值在于：它逼你拿真实行为当证据，而不是拿「感觉更好了」当证据。
name / description 两个必填字段，但 Claude Code 侧支持的字段是一整张表——allowed-tools / disallowed-tools / paths / model / effort / context: fork / hooks / disable-model-invocation……其中 license 与 compatibility 官方标注为「Agent Skills 规范字段」。你写惯了 Claude Code 的 skill，搬去别的 harness 会静默失效。ServerName:tool_name，例如 BigQuery:bigquery_schema、GitHub:create_issue。少了前缀，在挂了多个 MCP server 的环境里模型会找不到工具——官方 mcp-builder 走的就是这条规矩。/skill-doctor 会列出每个 skill 的 token 开销、调用频次，并标出从没被触发过的——那些通常不是没用，是 description 写得没进筛选。删掉或重写 description，别留着占位。先做这三件：① 把 template/SKILL.md 拷进 .claude/skills/ 当起手式（纯文本、零成本、永不过期）；② 装 skill-creator（/plugin install skill-creator@claude-plugins-official），冲的是它那套带基线对照的评估机器，不是起草；③ 把 /context 与 /skill-doctor 变成两周一次的习惯。
照着抄结构时：一件事多个深水区 → 抄模式 1（平铺 FORMS.md / REFERENCE.md）；多个域 → 抄官方 claude-api；要保证不出错 → 抄官方 docx 的解包-改-scripts/office/validate.py-重打包闭环。命令去 skill 真身抄，别抄文档里的示意路径。
硬数字备查：name ≤ 64 · description ≤ 1024 且第三人称 · Claude Code 列表按 1536 截断（硬砍）· 正文 < 500 行（软建议）· 引用一层深 · reference > 100 行加目录 · 至少 3 条评估 · Haiku/Sonnet/Opus 各测一遍 · metadata 常驻约 100 tokens/skill · 正文 5k tokens 以内。
动手顺序：不带 skill 跑一遍真活 → 记下具体失败 → 造三个场景 → 量基线 → 只写刚好够的字 → 对照基线迭代。别反过来先写文档。
name 与 description，各家 harness 可能另加字段。TIMEOUT = 47）。官方要求每个配置值都写清楚依据——你都不知道该取多少，模型更不知道。/skill-doctor（v2.1.252+）、/plugin validate（v2.1.233+）、/context、skill 目录层级skills/、spec/、template/ 三个目录加插件清单scripts/office/validate.py、scripts/merge_runs.py，以及 description 末尾那句负向触发词ServerName:tool_name 这条规矩的实际使用者skill-creator / mcp-builder 的装法与分层理由在那一期