# 一段描述，决定Skill生死：装机单上的门面设计拆解 ## 概述 本期观察换了个打法：不去追新仓库，而是把这台机器上真实装着的四百余件 Skills 的「门面」——frontmatter 里那个 description 字段——当作研究对象。样本全部取自本会话 Claude Code 注入的技能注册表，每一行引文都逐字来自真实环境，零脑补。核心发现有三条：其一，描述是这个生态真正的主战场，Skill 能不能被调用，先过描述关，正文写得再好也轮不到出场；其二，装机单上同时存在「裸名上架」与「精装上架」两种截然相反的策略，边界清晰得像两个物种；其三，最优秀的描述已经不是一句话广告，而是写进了触发条件、反触发排除、协商条款甚至内部分工的「条件程序」。本文逐条拆开这八个真实样本，最后给出可照抄的写法清单。 ## 一、描述的旅程：为什么它才是主战场 Skill 的加载机制决定了描述的命运。装上百来件 Skills 之后，如果把每一件的全文都塞进上下文，会话没开始就爆了。所以运行时的做法是：平时只把每件的名字和描述注入会话，等模型判断某条描述与当前任务匹配，才把那件 Skill 的正文全文展开。这个机制画出流程图是这样的： ```mermaid 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` 这一批，每一件都带着一段甚至十几行的描述原文被注入进来。 两个物种的生存策略完全不同： - **裸名派**把触发权交给用户。用户喊「libai」，名字本身就是触发词，描述没有存在的必要。它赌的是：我的名字足够独特，不需要机器猜意图。 - **精装派**把触发权交给模型。用户不会喊「claude-api」这个名字，但它要在用户说出「帮我迁移模型版本」时被模型主动匹配上。它赌的是：我的描述写得足够准，机器能在几百个候选里挑中我。 这个分野其实是生态成熟的标志。早期人人都写描述，生怕模型不懂；后来角色扮演类件发现用户永远会直接点名，描述字段就成了纯开销。于是出现了一个反直觉的结论：**描述不是写得越满越好，而是取决于你的触发权在谁手里**。触发权在用户手里，名字就是一切；触发权在模型手里，描述才是生死线。 插件命名空间是注册表里的第三个细节：`example-skills:pptx`、`obsidian:skill-creator` 这样的前缀说明，当技能来自插件市场时，注入名会带上命名空间前缀。这意味着精装派描述里如果引用自己的 slash 命令，还得考虑前缀一致性——又一个只在真机上才能看到的工程细节。 ## 三、八个真实样本逐条拆 先上评测表。维度换成描述设计特有的五项（正文中所有引文均为本机注册表原文照录）： | 样本 | 信息密度 | 触发精度 | 反触发防护 | 协商设计 | 综合评定 | |------|---------|---------|-----------|---------|---------| | claude-api | ★★★★★ | ★★★★★ | ★★★★★ | ★★★☆ | 最强工程化 | | deep-research | ★★★★★ | ★★★★☆ | ★★☆ | ★★★★★ | 最佳交互设计 | | update-config | ★★★★☆ | ★★★★★ | ★★★☆ | ★★★☆ | 最佳权责论证 | | code-review | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★★☆ | 分工最清晰 | | loop | ★★★☆ | ★★★★☆ | ★★★★★ | ★★★★★ | 反模式警示典范 | | fewer-permission-prompts | ★★★★☆ | ★★★☆ | ★★☆ | ★★☆ | 一句话流水线 | | simplify | ★★★☆ | ★★★★☆ | ★★★★★ | ★★★☆ | 划界艺术 | | verify | ★★☆ | ★★★☆ | ★☆ | ★☆ | 极简主义 | ### 3.1 claude-api：把 if-else 写进门面 这是装机单上最重的一条描述，重到值得逐段读。开头是三个动词： > 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)` 顺带展示了另一个技巧：把具体版本对写进描述，让「迁移模型」这种请求的匹配精度直接拉满。 ### 3.2 deep-research：把澄清问题前置到门面 > 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 还交代了澄清结果如何回注流程。一条描述，本质是一篇压缩到极致的交互协议。 ### 3.3 update-config：一句权责论证顶十句功能罗列 > 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"）——把用户实际会说出口的话直接写进描述做匹配锚点，这是精装派里最贴地气的写法。 ### 3.4 code-review：把档位和使用方式写进说明书 > 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」式的划界在下面这件上还能看到变体。 ### 3.5 loop：把反模式警告写上门面 > 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 块异曲同工，只是一个防「错误场景」，一个防「错误姿势」。 ### 3.6 fewer-permission-prompts：一句话装下一条流水线 > 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. 扫描会话记录、聚合高频只读调用、生成优先级排序的允许清单、写回项目配置——四个动作一口气写在一句里，连目的（减少权限弹窗）都交代了。它是「极简但不简陋」的代表：没有一个多余的字，也没有漏掉一个必要的环节。 ### 3.7 simplify 与 verify：划界与极简的两个极端 > 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」这半句正是它和「只做静态检查」那类件的全部区别。 ## 四、五种写法模式 把八个样本收拢，描述设计其实就五种模式： ```mermaid 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 即可被注册表收录；随插件分发的技能则会带上 `插件名:技能名` 的命名空间前缀。安装后无需重启会话的验证办法也简单：新开会话观察技能是否出现在可用列表、描述是否被完整注入。 ## 六、给未来 Skill 作者的六条清单 1. **先问触发权在谁手里。** 用户会点名喊你的，砍掉描述；需要模型主动匹配的，描述值得花掉你一半的写作时间。 2. **动词开头，三连击。** Build, debug, and optimize——一句话覆盖用户请求的三种姿势，比「这是一个用于……的工具」高效十倍。 3. **给一个具体反例。** deep-research 那句「what car to buy 缺预算、用途、地区」证明，一个反例胜过十句抽象要求。 4. **写清你不管什么。** SKIP 块、Do NOT 段、划界条款，都是防误触发的。描述只写热情的招募语而不画边界，是新手最常见的事故源。 5. **协商条款前置。** 默认值（defaults to 10m）、澄清时机（BEFORE invoking）、结果回注方式（weaving the answers in）——这些契约写在门面，模型在决策时刻就能遵守。 6. **有权责论证就写上。** update-config 那句「the harness executes these, not Claude, so memory/preferences cannot fulfill this」说明：能一句话说清「为什么非我不可」的 Skill，才真正站住了生态位。 ## 推荐排行榜 - **最佳工程化**：claude-api —— TRIGGER/SKIP 双块结构，当前描述写作的天花板。 - **最佳交互设计**：deep-research —— 把澄清协议压缩进描述，few-shot 反例教科书。 - **最佳权责论证**：update-config —— 一句话讲透不可替代性。 - **最佳划界**：simplify + code-review —— 互为镜像的分工条款。 - **最佳反模式警示**：loop —— Do NOT 写在触发前。 - **最佳极简**：verify —— 一句话方法论，无一字可删。 ## 参考来源 1. 本机 Claude Code 会话注入的技能注册表（2026-09-26 会话）——本文全部八条描述引文与裸名派/精装派统计的原始出处，引文逐字照录。 2. 本机 example-skills 与 obsidian 插件的命名空间注入样本——`插件名:技能名` 前缀机制的观察依据。 3. 本专栏往期拆解存档（pcap-generator、planning-with-files、dsh-agent-teams、官方 pptx 等篇）——装机单生态史与选题查重的对照基准。 > 说明：本期写作期间在线搜索与抓取通道均不可用，故样本全部取自本机可验证的注册表原文；文中未给出任何在线链接，以免虚构。延伸阅读可关注官方示例仓库 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 等场景全覆盖。