本期观察换了个打法：不去追新仓库，而是把这台机器上真实装着的四百余件 Skills 的「门面」——frontmatter 里那个 description 字段——当作研究对象。样本全部取自本会话 Claude Code 注入的技能注册表，每一行引文都逐字来自真实环境，零脑补。核心发现有三条：其一，描述是这个生态真正的主战场，Skill 能不能被调用，先过描述关，正文写得再好也轮不到出场；其二，装机单上同时存在「裸名上架」与「精装上架」两种截然相反的策略，边界清晰得像两个物种；其三，最优秀的描述已经不是一句话广告，而是写进了触发条件、反触发排除、协商条款甚至内部分工的「条件程序」。本文逐条拆开这八个真实样本，最后给出可照抄的写法清单。
Skill 的加载机制决定了描述的命运。装上百来件 Skills 之后，如果把每一件的全文都塞进上下文，会话没开始就爆了。所以运行时的做法是：平时只把每件的名字和描述注入会话，等模型判断某条描述与当前任务匹配，才把那件 Skill 的正文全文展开。这个机制画出流程图是这样的：
flowchart TD
A["SKILL.md 头部信息"] --> B["description 字段"]
B --> C["注册表注入会话"]
C --> D{"用户请求到达"}
D --> E["描述与请求匹配"]
E --> F["正文全文展开"]
F --> G["模型按正文执行"]
E --> H["匹配失败静默沉底"]
这张图里藏着一个残酷的事实：H 节点（匹配失败静默沉底）是大多数 Skill 的终点。描述写得含糊，模型就不会选你；模型不选你，正文里三千字的精心设计永远不会被读到。作者的全部心血，压缩在描述那一行里参加海选。
这就是为什么说描述是主战场——它是唯一一个「每轮对话都在参赛」的部件。正文是面试时的作品集，描述是简历上那行个人简介，而筛选官每次只扫一眼。
把本会话注入的注册表从头翻到尾，会看到一个泾渭分明的分界线。按名称模式粗略统计（口径：以 -skill 后缀及人名规则命名，以本机注册表为准），三百个上下的技能是「裸名派」——libai-skill、zoro-skill、zhouxingchi-skill、heshen-skill……在注入列表里，它们只有一个名字，没有描述文本。
另一边是不足二十件的「精装派」——claude-api、deep-research、code-review、verify、run、loop、update-config、simplify、fewer-permission-prompts、keybindings-help 这一批，每一件都带着一段甚至十几行的描述原文被注入进来。
两个物种的生存策略完全不同：
这个分野其实是生态成熟的标志。早期人人都写描述，生怕模型不懂；后来角色扮演类件发现用户永远会直接点名，描述字段就成了纯开销。于是出现了一个反直觉的结论：描述不是写得越满越好，而是取决于你的触发权在谁手里。触发权在用户手里，名字就是一切；触发权在模型手里，描述才是生死线。
插件命名空间是注册表里的第三个细节：example-skills:pptx、obsidian:skill-creator 这样的前缀说明，当技能来自插件市场时，注入名会带上命名空间前缀。这意味着精装派描述里如果引用自己的 slash 命令，还得考虑前缀一致性——又一个只在真机上才能看到的工程细节。
先上评测表。维度换成描述设计特有的五项（正文中所有引文均为本机注册表原文照录）：
| 样本 | 信息密度 | 触发精度 | 反触发防护 | 协商设计 | 综合评定 |
|---|---|---|---|---|---|
| claude-api | ★★★★★ | ★★★★★ | ★★★★★ | ★★★☆ | 最强工程化 |
| deep-research | ★★★★★ | ★★★★☆ | ★★☆ | ★★★★★ | 最佳交互设计 |
| update-config | ★★★★☆ | ★★★★★ | ★★★☆ | ★★★☆ | 最佳权责论证 |
| code-review | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★★☆ | 分工最清晰 |
| loop | ★★★☆ | ★★★★☆ | ★★★★★ | ★★★★★ | 反模式警示典范 |
| fewer-permission-prompts | ★★★★☆ | ★★★☆ | ★★☆ | ★★☆ | 一句话流水线 |
| simplify | ★★★☆ | ★★★★☆ | ★★★★★ | ★★★☆ | 划界艺术 |
| verify | ★★☆ | ★★★☆ | ★☆ | ★☆ | 极简主义 |
这是装机单上最重的一条描述，重到值得逐段读。开头是三个动词：
Build, debug, and optimize Claude API / Anthropic SDK apps.
动词打头，三个动作覆盖了用户可能的三种请求姿势。紧接着第一句就是观点而非功能：
Apps built with this skill should include prompt caching.
注意，这不是在说「我支持什么」，而是在说「用我就等于拿到最佳实践」——把观点预置进门面，模型一旦展开正文， caching 已经是既定方针。
然后是全样本里独一无二的 TRIGGER/SKIP 双块结构。TRIGGER 块从三个层面列触发条件：
TRIGGER when: code imports
anthropic/@anthropic-ai/sdk; user asks about the Claude API...; building/tuning a Claude feature (caching, thinking, tool use, batch use...).
第一层看代码特征（import 了什么包），第二层看用户意图（问了什么问题），第三层看任务类型（在做什么功能）。三层条件覆盖了「用户没明说但代码会说话」的场景——用户只丢来一个文件，模型看一眼 import 就知道该不该叫它。
SKIP 块则更精妙，这是全装机单唯一的反触发设计：
SKIP: file imports
openai/other-provider SDK; filename like*-openai.py,*-generic.py; provider-neutral code...
反触发解决的是「误触发」这个描述设计的暗面问题。触发条件写得越热情，越容易在无关场景里被错误唤醒，浪费上下文。claude-api 的作者用文件名通配符 *-openai.py 把竞争 SDK 的文件直接挡在门外。同一段描述里既有「什么时候用我」也有「什么时候别用我」，这才是一件完整把自己边界画清楚的作品。最后括号里的 (4.5 → 4.6, 4.6 → 4.7, retired-model replacements) 顺带展示了另一个技巧：把具体版本对写进描述，让「迁移模型」这种请求的匹配精度直接拉满。
Deep research harness — fan-out web searches, fetch sources, adversarially verify claims, synthesize a cited report.
开头用一行把流水线四个步骤全部报出：扇出搜索、抓取来源、对抗式核查、汇总成带引用的报告。用户读一眼就知道这不是普通搜索。
真正值钱的是后半段：
BEFORE invoking, check if the question is specific enough to research directly — if underspecified (e.g., "what car to buy" without budget/use-case/region), ask 2-3 clarifying questions...Then pass the refined question as args, weaving the answers in.
这段话干了三件事。第一，用 BEFORE invoking 把时序写死：澄清必须发生在调用之前，不是调用之后发现问题再问。第二，内嵌了一个完整的 few-shot 反例——「what car to buy 缺预算、用途、地区」——用最具体的例子告诉模型什么叫「不够具体」，比十句抽象定义都管用。第三，连澄清问题都给了精确数量「2-3 个」，收尾的 weaving the answers in 还交代了澄清结果如何回注流程。一条描述，本质是一篇压缩到极致的交互协议。
Automated behaviors ... require hooks configured in settings.json - the harness executes these, not Claude, so memory/preferences cannot fulfill this.
这句是全装机单我最佩服的一句话。它没有罗列功能，而是先回答「为什么这件事必须用我」：因为这类行为的执行者是 harness 而非 Claude，所以用户跟 Claude 说「以后每次都这样」是没用的，记忆机制根本执行不了，必须落到 settings.json 的 hooks 上。
一个 Skill 的描述能说出「我的不可替代性在哪」，这标志着作者真的想清楚了生态位。后半段用两个 Also use for 把周边场景全部收编：权限、环境变量、hook 排障，并内嵌了请求原话示例（"allow X"、"set DEBUG=true"）——把用户实际会说出口的话直接写进描述做匹配锚点，这是精装派里最贴地气的写法。
Review the current diff for correctness bugs and reuse/simplification/efficiency cleanups at the given effort level (low/medium: fewer, high-confidence findings; high→max: broader coverage, may include uncertain findings).
这一句描述同时交代了「查什么」（正确性 bug 与四类清理）和「力度档位怎么影响产出」（低档少而准，高档广而容忍误报）。用户调 --fix 与否会得到不同的行为，而模型在展开正文之前就已经知道了这层契约。
它的分工条款也值得单拎出来：涉及「审什么」的判断交给它，纯 bug 猎捕则被明确让渡——「this doesn't hunt for bugs; use /code-review for that」式的划界在下面这件上还能看到变体。
Do NOT invoke this skill for: background work you started — when harness-tracked work finishes, you are re-invoked automatically, so polling is wasted.
全样本唯一的「Do NOT」段落。它预防的场景极其真实：用户让 Agent 盯一个后台任务，模型出于惯性每三十秒轮询一次——而 harness 本身会在任务结束时重新唤醒模型，轮询纯属浪费。这句警告不写在正文里而写在门面上，意味着它在「要不要调用」的决策时刻就能生效——防误用防在触发前，和 claude-api 的 SKIP 块异曲同工，只是一个防「错误场景」，一个防「错误姿势」。
Scan your transcripts for common read-only Bash and MCP tool calls, then add a prioritized allowlist to project .claude/settings.json to reduce permission prompts.
扫描会话记录、聚合高频只读调用、生成优先级排序的允许清单、写回项目配置——四个动作一口气写在一句里，连目的（减少权限弹窗）都交代了。它是「极简但不简陋」的代表：没有一个多余的字，也没有漏掉一个必要的环节。
Use when asked to ... This doesn't hunt for bugs; use /code-review for that.
simplify 的描述价值全在后半句：明确宣布「我不抓 bug，抓 bug 找 /code-review」。多 Skill 共存时最怕的就是两件同时抢一个请求，一句划界条款省掉了模型的选择困难，也省掉了用户解释的口舌。它和 code-review 互为镜子：一件用 TRIGGER/SKIP 管自己的边界，一件用一句话管别人的地盘。
verify 则是另一个极端：
Verify that a code change actually does what it's supposed to by running the app and observing behavior.
一句话说完方法论（跑起来、看行为，而不是看代码），再加一串用例枚举。信息密度低是它被扣星的原因，但换个角度，它的每一个词都不可删——「running the app and observing behavior」这半句正是它和「只做静态检查」那类件的全部区别。
把八个样本收拢，描述设计其实就五种模式：
flowchart TD
subgraph S1["一句话型"]
A1["verify"]
A2["fewer-permission-prompts"]
end
subgraph S2["条件编程型"]
B1["claude-api 触发块"]
B2["claude-api 反触发块"]
end
subgraph S3["协议协商型"]
C1["loop 默认值与禁用"]
C2["deep-research 先澄清"]
end
subgraph S4["划界型"]
D1["simplify 让出抓bug"]
D2["update-config 权责论证"]
end
subgraph S5["裸名型"]
E1["数百件人物技能"]
E2["名字即触发词"]
end
五种模式对应五种触发权的分配方式：裸名型把触发权全给用户，一句话型信任模型的常识判断，条件编程型用显式规则接管判断，协议协商型在描述里预置了讨价还价的空间，划界型则承认生态是多件的、先把邻里关系写清楚。没有高低之分，只有适不适合——但可以确定的是，越往工具链深处走，条件编程和协议协商的比重越大，因为那些场景里「误触发」和「错误姿势」的代价远高于角色扮演件。
本文拆的八件均为 Claude Code 内置或随插件装配，本机开箱即有，无需安装。对想复用这些设计写自己 Skill 的读者，通用装配路径只有一步：在你的技能目录（用户级 ~/.claude/skills/<名称>/ 或项目级 .claude/skills/<名称>/）下放置 SKILL.md，frontmatter 里写好 name 与 description 即可被注册表收录；随插件分发的技能则会带上 插件名:技能名 的命名空间前缀。安装后无需重启会话的验证办法也简单：新开会话观察技能是否出现在可用列表、描述是否被完整注入。
插件名:技能名 前缀机制的观察依据。说明：本期写作期间在线搜索与抓取通道均不可用，故样本全部取自本机可验证的注册表原文；文中未给出任何在线链接，以免虚构。延伸阅读可关注官方示例仓库 anthropics/skills 与各大 Skills 目录站（skills.sh、skillsmp.com、skillsdirectory.com、mcpservers.org/agent-skills），上述站点本次均未能在线验证，数据以官方页面为准。
[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。