# 一个字段定生死：从430个实装Skill拆触发层设计 ## 概述 装了一个 Skill 却从来不被触发，是这个生态里最沉默的失败——不报错、不提示，Skill 就在磁盘上过完一生。本文把镜头从 SKILL.md 正文拉回到它上面的那几行 frontmatter：`name` 与 `description`。这是 Skill 唯一常驻模型上下文的「广告位」，正文写得再好，触发层失守就等于没写。语料来自两处：本机实装的 430+ 个 Skill 注册表（可逐条核对原文），以及本周（2026-09-05 至 09-12）新上架的一批高星 Skill。从中提炼出六种经得起复用的描述写法、两种典型反面模式，并给出一个可以直接照抄的写作模板。 ## 触发层在哪：一张图看懂 Skill 的三层漏斗 按 Anthropic 官方文档对 Agent Skills 机制的说明，Skill 采用渐进披露：`name` 和 `description` 随已装 Skill 清单常驻上下文，SKILL.md 正文在判定相关后才加载，正文里引用的脚本和资源文件再下一层按需读取。据官方文档，frontmatter 有硬约束：name 最长 64 字符，description 最长 1024 字符（以官方文档为准）。这意味着触发层是整条链路里**唯一 100% 会被看见的部分**： ```mermaid flowchart TD A["用户输入一句话"] --> B["常驻层：全部已装 Skill 的 name 与 description"] B --> C{"语义匹配？"} C -->|命中| D["按需加载：SKILL.md 正文进入上下文"] C -->|未命中| E["Skill 沉睡，本次任务不参与"] D --> F["正文引用的资源文件按需读取"] F --> G["scripts 直接执行，输出回填"] ``` 这张图还解释了一个容易被忽略的经济学问题：**上下文税**。本机装了 430+ 个 Skill，就是 430 多份描述在每一次对话里占着 token。写得越啰嗦，常驻成本越高；写得越含糊，越可能永远沉睡。触发工程就是在「必须说清」和「必须省字」之间走钢丝。 ## 评测对比表 | 对象 | 出处 | 功能完整度 | 设计质量 | 实战效果 | 上手难度 | 社区活跃度 | |------|------|-----------|---------|---------|---------|-----------| | claude-api | 本地实装 | ★★★★★ | ★★★★★ | ★★★★★ | ★★★★ | ★★★★ | | deep-research | 本地实装 | ★★★★★ | ★★★★★ | ★★★★★ | ★★★★ | ★★★★ | | verify | 本地实装 | ★★★★ | ★★★★★ | ★★★★ | ★★★★★ | ★★★★ | | update-config | 本地实装 | ★★★★ | ★★★★★ | ★★★★ | ★★★★★ | ★★★ | | anything2explainer | 新架 ⭐929 | ★★★★ | ★★★★ | ★★★ | ★★★★ | ★★★★ | | dream-loop | 新架 ⭐842 | ★★★★ | ★★★★ | ★★★ | ★★★ | ★★★★ | | ffmpeg-skill | 新架 ⭐965 | ★★★★ | ★★ | ★★★ | ★★★★ | ★★★★ | | stop-that-shit | ⭐1915 | ★★★ | ★★★★ | ★★★ | ★★★ | ★★★★ | ## 六种写法：从真实描述里提炼 ### 第一式：双清单式——正面触发 + 负面排除 样本是官方出品、本机实装的 `claude-api`。它的 description 分三段：先说做什么（"Build, debug, and optimize Claude API / Anthropic SDK apps"），然后是明确的正面清单： > TRIGGER when: code imports 'anthropic'/'@anthropic-ai/sdk'; user asks for the Claude API, Anthropic SDK, or Managed Agents; user adds/modifies/tunes a Claude feature (caching, thinking, tool use, batch, files, citations, memory). 关键在第三段——大多数作者根本想不到要写的**负面清单**： > SKIP: file imports 'openai'/other-provider SDK, filename like '*-client.py', provider-neutral programming/ML. 为什么这行值钱？因为「帮我把这段 OpenAI 调用改成兼容写法」这类请求在语义上和 Claude API 高度相邻，没有 SKIP 清单，模型很容易误触发。双清单式的本质是把「该我上」和「不该我上」都写成判决书，触发精度直接拉满。可复制点：任何容易和竞品、邻近领域混淆的 Skill，都值得补一条 SKIP。 ### 第二式：原话钩子式——把用户的口语埋进描述 `update-config` 的 description 里塞了一堆带引号的短句： > Automated behaviors ("from now on when X", "each time X", "before/after X") require hooks configured in settings.json... Examples: "allow npm commands", "add permission", "set DEBUG=true". 这些引号里不是装饰，是**用户最可能说出的原话**。触发匹配走的是语义相似度，而用户原话就是相似度最高的锚点。当你说「以后每次提交前都跑测试」，这句和描述里的 "from now on when X" 几乎逐词对上，触发概率远高于一段文绉绉的功能介绍。可复制点：写完描述后问自己——用户会用哪句中文/英文喊出这个需求？把那句话（或其英文等价物）直接埋进去。 ### 第三式：门槛澄清式——把调用前置条件写进触发层 `deep-research` 的描述在触发条件之后追加了这样一段： > BEFORE invoking, check if the question is specific enough to research — if underspecified (e.g., "what car to buy"), ask 2-3 clarifying questions to narrow scope. 这是一种防误伤设计：深度调研是高成本动作（大量搜索、大量 token），一旦被模糊问题误触发就是纯浪费。它把「先澄清再启动」写进了触发层本身，等于在门口装了一道安检。顺带注意它的手法——"what car to buy" 又是一个原话钩子，两式叠加。可复制点：凡是烧 token 重的 Skill（调研、批量生成、大规模重构），都应该在描述里写明「什么情况下先别调用我」。 ### 第四式：场景枚举式——一句话定位加 Use when 列表 本地实装的 `verify` 和 `run` 是这个流派的标准写法。`verify`： > Verify that a code change actually does what it's supposed to by running the app and observing behavior. Use when asked to verify a PR, confirm a fix works, test a change manually, check if a PR works, or validate local changes before pushing. `run`： > Launch and drive this project's app to see a change working. Use when asked to run, start, or screenshot the app... 结构高度一致：第一句动词开头说清「做什么」，第二句 "Use when" 枚举四五个触发场景。没有修辞，没有形容词，每个短语都是一个可命中的语义坐标。这是最不惊艳但最稳的写法——生态里大多数高质量 Skill 都属于这一派。可复制点：第一句不超过 20 个词，Use when 至少列 3 个场景，每个场景用不同的动词开头（verify / confirm / test / validate），扩大命中面。 ### 第五式：出入口式——「X 进 Y 出」一句话讲清卖点 本周新架的高星仓库里，这个写法集中出现。`anything2explainer`（⭐929）的仓库简介只有一句： > Topic in, narrated explainer video out. A Claude Code / Codex skill that turns any topic into a blackboard-style explainer video. 前半句是格式化极强的「输入进、成品出」，后半句补一句定位。`dream-loop`（⭐842）同理： > Agent skill for impressive 3D visuals using Blender + image gen + subagent critic. ### 第六式：关键词裸奔式——没有描述，赌一个名词 ## 两种反面模式 **人名海模式。** 本机注册表里，`*-skill` 后缀的人名/角色 Skill 超过一百个：libai-skill、caocao-skill、conan-skill、zhouxingchi-skill……它们的 name 即关键词，description 退化为人设说明。这个物种能存活，是因为「模仿某人写作/说话风格」的触发请求天然带着人名。但它展示了 name 与 description 的分工被推到极端后的形态：名字负责被找到，描述只剩人格化。对普通作者没有参考价值，除非你做的正是角色扮演类。 **形容词堆叠模式。** 翻遍注册表，凡是描述里出现「强大的」「专业的」「next-generation」这类词的 Skill，几乎都伴随另一个症状：没有 Use when、没有场景、没有原话。形容词不参与语义匹配——用户不会说「给我来个强大的东西」。判断标准很简单：把描述里的形容词全删掉，如果剩下的信息量为零，这条描述就没写完。 ## 动手写你的第一个 description 把六式压成一个可直接套用的模板，四段各司其职： ```mermaid flowchart TD T["一条合格的 description"] --> L1["第一句：动词开头，说清做什么"] T --> L2["第二段：Use when 列 2-3 个触发场景"] T --> L3["第三段：Skip 排除 1 个易混淆场景"] T --> L4["收尾：埋入用户原话与关键名词"] ``` 配套检查单五条： 1. **动词开头**：第一句以 Build / Verify / Convert / Generate 类动词起手，不说「这是一个……的 Skill」。 2. **至少三个触发场景**：每个场景换一个动词，覆盖用户可能的不同说法。 3. **有一条 Skip**：想一个最容易被误触发的邻近场景，明确排除。 4. **埋一句原话**：用户会脱口而出的那句话，加引号放进描述。 5. **删光形容词**：删完后重读，信息量不能归零。 一句话定位仍然讲不清输入输出的，先回去改 Skill 设计——描述治不了设计病。 ## 推荐排行榜 **描述设计教科书榜（可逐行抄）**： 1. claude-api —— 双清单式的完整范本，TRIGGER/SKIP 结构最值得抄 2. deep-research —— 门槛澄清式独一档，高成本 Skill 必学 3. update-config —— 原话钩子密度最高 **最该回头补描述榜**： 1. ffmpeg-skill（⭐965）—— 空描述裸奔，星高不代表触发稳 2. screenwriting-skills（⭐743）—— 同上，全押一个名词 ## 参考来源 > [!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 等场景全覆盖。