# 拆九段在跑描述：触发词工程课 ## 概述 大多数人学写 Skill，都把力气花在正文上——流程写得漂漂亮亮，步骤编排得井井有条，然后发现模型根本不调用它。问题不在正文，在 frontmatter 里那两行的 `description`。它是唯一一个在 Skill 上岗之前就被模型反复阅读的字段，是路由层，是广告位，是你唯一能争取到的「面试机会」。本文不谈新仓库、不做周报，而是把一台真实装机环境里正在运行的九段 Skill 描述原文摊开，逐段解剖它们各自的写法套路，最后给你一个可以直接照抄的五段式模板。看懂这九段，你的第一个 Skill 就不会死在没人叫它的那一步。 ## 一、先看一份四百件的装机清单 一台重度使用的 Claude Code 环境，`~/.claude/skills/` 下会积累出什么？ 粗粗一数，四百件上下。其中一百五十件以上是「人物件」——命名清一色 `人名-skill`：`zhouxingchi-skill`、`heshen-skill`、`luxun-skill`，从周星驰排到鲁迅，从和珅排到诸葛丞相，连葫芦兄弟都按 `huluwa-erwa` 到 `huluwa-qiwa` 一人一席占足七件。这是清单的第一大类：把某个人的说话方式、思维套路封装成一个可调用的「人格插件」。 第二类值得看的是「同位多件」——同一个功能位上，堆着好几件竞争者： - 表格写作位：`pptx`、`pptx-generator`、`pptx-manipulation`、`pptx-official`、`pptx-test`，加上 `ericsson-ppt-writer` 三个版本和 `51xtx-ppt-writer`，整整九件挤一个工位； - 抓包位：`pcap-analyzer`、`pcap-generator`、`pcap-modifier`，分析、生成、改写各一件，分工清楚； - 课程视频位：`course-video-maker` 拖着一个四件家族——`-link`、`-zh`、`-zh-link` 三个变体； - 部署位：`vercel-deploy`、`netlify-deploy`、`cloudflare-deploy`、`render-deploy`，四家平台一家一件； - 名字完全相同的 `skill-creator`，在这个环境里注册了三处：本地一份、官方示例集一份、obsidian 插件一份。 九件 PPT 写手同时在线，用户只说一句「帮我做个 PPT」，模型调谁？答案由一个东西决定：每件 SKILL.md 头部那几行描述。描述写得含糊的，永远轮不上；描述写得准的，四百件里一击命中。 这就是本文要解剖的那一层。 ## 二、描述不是简介，是路由表 先建立一个关键认知：SKILL.md 的结构分两层，命运完全不同。 ``` --- name: my-skill description: ……（这一行决定生死） --- （正文：这一行决定上岗后干得好不好） ``` 模型每次收到用户输入，会拿这句话去扫描全部已注册 Skill 的 `description` 字段——注意，只是描述，正文一个字都不会被读。描述命中了，Skill 被装载，正文才进入上下文；描述没命中，你正文写得再好都是死文档。 所以描述的工程目标只有一个：**让模型在对的时机选中你，在错的时机放你过**。少半句，该叫你不叫；多半句，不该叫你乱叫。九段在跑的描述，恰好展示了九种把这一行写到位的手法。 ## 三、九段描述逐段解剖 ### 第 1 段：claude-api —— 双闸门模式 最值得精读的一段。它的描述分三个块：先一句功能总述（构建、调试、优化 Claude API 应用，顺带处理模型版本迁移），然后是两个关键词打头的清单： - **TRIGGER when**：代码 import 了 `anthropic` / `@anthropic-ai/sdk`、用户问到 Claude API、用户在调缓存/思考/工具调用等特性、问到 prompt caching 命中率——四条进场条件，条条可被代码和对话直接验证； - **SKIP**：文件 import 的是 `openai` 或其他厂商 SDK、文件名带 `*-openai.py`、供应商中立代码、泛泛的编程/机器学习问题——四条退场条件。 这是描述工程的最高配形态：**正反两张闸门**。TRIGGER 回答「什么时候必须叫我」，SKIP 回答「什么时候看起来该叫我但其实不该」。没有 SKIP 的描述，容易在「用户聊到 AI 编程」这种宽泛场景被误触发，一次误触发就是一次上下文污染。你写第一个 Skill 未必需要双闸门，但只要你的 Skill 与相邻领域有混淆可能，SKIP 那一行就值回票价。 ### 第 2 段：update-config —— 人话翻译模式 这一段解决的是另一个致命问题：**用户嘴里说的话，和机制术语对不上**。它的描述里先声明「自动行为类请求（『从现在起每次……』、『每次都……』、『之前/之后……』）需要 hooks，而 hooks 要写进 settings.json」，然后把用户的原话直接收录进描述：「allow npm commands to run without asking」「set DEBUG=true」「when claude stops show the total duration」。 用户说「以后跑 npm 别老问我」，这句话里没有一个字提到 hooks、settings.json、permission。如果描述只写「修改 settings.json 的工具」，模型匹配不上，这单就漏接了。把目标用户最可能脱口而出的话术原文抄进描述，等于在路由表里预埋了同声传译。写法要点：例句要抄「用户会说的话」，不是「你能做的事」——这两者词汇分布完全不同。 ### 第 3 段：code-review —— 档位语义模式 它的描述里直接写明了参数档位的行为差异：低档位出报告「更少但置信度高」，高档位「覆盖更广但可能包含误报」，还写清了 `--comment` 会把结果发成 PR 评论、`--fix` 会直接动手修。 这一段的价值在于：调用方在**发起调用之前**就知道自己买的是什么。这不仅是用户体验，更是路由辅助——用户说「快速过一眼 diff」，模型看到「low = 少而准」，自然选中它并用低档跑。把可调参数的语义写进描述，等于给了模型一张点菜单，而不是让它点完才发现没有。 ### 第 4 段：verify —— 边界声明模式 verify 的描述开头是功能（跑起应用、观察行为、验证改动真的生效），紧跟着一连串「Use when」：被要求验证 PR、确认修复有效、手动测试改动、看截图确认。它的姊妹篇 simplify 则专管另一件事——复用、简化、效率、抽象层级的清理——并且描述末尾专门补一句：它**不做**正确性 bug 排查，那归 code-review。 这就是边界声明的写法：**不仅说清我做什么，还说清我隔壁那位做什么**。在多个 Skill 共存的环境里，相邻 Skill 之间把分工写进各自的描述，是避免抢单、漏单的根本手段。这不是巧合，是设计职责——你在写描述时，应该抬头看一眼注册表里的邻居，主动在描述里划清地界。 ### 第 5 段：run —— 动词清单模式 run 的描述极短：启动并驱动本项目的应用，看看改动是否真的能跑。然后是触发场景清单：被要求 run、start、screenshot 应用，或确认改动生效。 它的可学之处在于**动词覆盖面**。同一个用户意图，有人会说「跑起来」，有人会说「启动」，有人会说「截个图看看」，有人会说「验证一下能不能用」。描述里把这些高频动词都点到，路由命中面就宽。新手最常见的错误是描述里只写自己选定的那个标准动词，而真实用户的话语里有五六个变体。 ### 第 6 段：loop —— 示例前置模式 loop 的描述第一句就把完整用例写进去了：「按周期循环执行一个 prompt 或斜杠命令（如 `/loop 5m /foo`，默认间隔 10 分钟）」。 示例直接内嵌进描述，好处有两层：模型在决定是否调用时就能看到标准用法，调用后传参出错的概率大降；而且示例本身就是最强触发信号——用户输入长得像示例时，相似度匹配天然偏高。一行示例，顶三行功能说明。 ### 第 7 段：deep-research —— 反问条件模式 deep-research 的描述里有一段罕见的内容：**指导模型在调用之前先做什么**。原文写明——如果问题太宽泛（比如「什么车值得买」却没说预算和用途），先问两三个澄清问题，再把精炼后的问题传进去。 这是描述的进阶用法：描述不只是路由信号，还可以携带「前置协议」。什么时候该反问、反问完怎么把答案织回任务——这些本该写在正文里的流程，有一小截被提到了描述层。适用于那些「问错就是大浪费」的 Skill：研究、下单、发消息，都属于此类。 ### 第 8 段：fewer-permission-prompts —— 行为闭环模式 这一段的描述一句话说完整个闭环：扫描你的历史会话记录，找出常见的只读 Bash 和 MCP 工具调用，然后把它们按优先级整理成允许清单，写进项目的 `.claude/settings.json`。 输入（transcripts）、加工（筛选常见只读调用）、输出（allowlist 写入指定文件），一句话里全齐。这种写法适合工具型 Skill：**动词 + 对象 + 产物落点**，三个要素一个不缺。模型对这种「有头有尾有交付物」的描述信任度最高，因为调用它的结果可预期。 ### 第 9 段：update-config 之外的全员共识 —— 一句话总述开头 回头看，九段描述有一个共同点：**第一句永远是功能总述，二十个词以内，动词开头**。claude-api 是「Build, debug, and optimize…」，loop 是「Run a prompt or slash command…」，verify 是「Verify that a code change actually does…」。没有一段以背景介绍、设计理念或版本历史开头。 这不是审美，是工程：描述的第一句承担着最高频的匹配任务，每一个多余的词都在稀释信号。总述句的配方是「动词 + 做什么 + 给谁用」，其余一切（触发条件、例句、档位、边界）全部后置。 ## 四、五种模式对照表 | 模式 | 教材 | 适用场景 | 上手收益 | 写作成本 | |------|------|----------|----------|----------| | 双闸门（TRIGGER/SKIP） | claude-api | 与相邻领域易混淆的 Skill | ★★★★★ | 中 | | 人话翻译（收录用户原话） | update-config | 面向非技术用户的工具 | ★★★★★ | 低 | | 档位语义（参数写进描述） | code-review | 有强弱档位的分析类工具 | ★★★★ | 低 | | 边界声明（说清邻居是谁） | verify / simplify | 多 Skill 共存环境 | ★★★★ | 低 | | 示例前置（内嵌用法样例） | loop / deep-research | 命令型、研究型 Skill | ★★★☆ | 低 | | 行为闭环（动词+对象+产物） | fewer-permission-prompts | 一次性工具型 Skill | ★★★ | 低 | 五模式不必全上。第一个 Skill 的推荐组合：一句话总述 + TRIGGER 清单 + 两条用户原话例句，二十分钟可以写完，已经胜过市面上大半只写功能不写触发的描述。 ## 五、一段描述的完整旅程 ```mermaid flowchart TD A["用户一句话"] --> B["模型扫描注册表"] B --> C{"拿话对描述"} C -->|命中总述关键词| D{"核对TRIGGER清单"} C -->|疑似沾边| E{"核对SKIP清单"} D -->|条件满足| F["装载正文"] E -->|条件命中| G["保持静默"] F --> H["Skill上岗干活"] ``` 这张图解释了两个常见冤案：其一，你 Skill 没被调用，多半死在 C 到 D 这一跳——描述里根本没有用户会说的词；其二，你的 Skill 被莫名其妙调用，死在 E 这一跳——没有 SKIP 闸门，疑似沾边就进场。 ## 六、现在写你的第一个 Skill 五段式模板，直接抄： ```markdown --- name: weekly-report description: 生成结构化的周报，从 git log 与任务清单提取本周产出。 TRIGGER when: 用户要求写周报、周总结、work log、本周汇报； 用户提供日期区间要求汇总工作内容。 例句："帮我写这周的周报""把这几个 commit 整理成周报"。 SKIP: 单纯的 git log 查看、与工作产出无关的日常总结。 --- （正文从这里开始：输入格式、输出格式、 处理步骤、边界情况，按操作手册的写法展开） ``` 安装只需一个目录约定： ```bash mkdir -p ~/.claude/skills/weekly-report # 把上面的内容存为该目录下的 SKILL.md # 重启会话后，新 Skill 即出现在注册表中 ``` 三个动作：总述句动词开头、TRIGGER 抄用户会说的话、与邻居划清边界。写完之后，用一句用户最可能说的话去测——模型叫不叫它，一分钟见分晓。叫了，描述合格；没叫，回来在描述里补上你刚才那句原话，再测。这个循环就是 Skill 描述工程的全部迭代方式，比读十篇教程都管用。 如果想要机器帮着起稿，本机注册表里的 `skill-creator` 就是干这个的：把需求说给它，它按官方规范生成骨架，你再回头按本文的五段式打磨描述。造件工具已经就位，缺的只是你对「那一行描述」的敬畏。 ## 七、模式优先级排行 1. **一句话总述**（动词开头，二十词内）——没有它一切免谈，新手第一优先； 2. **TRIGGER 清单**（抄用户原话，不抄功能名词）——解决「没人叫我」的头号病因； 3. **SKIP 清单**——解决「乱入」与「污染」，多 Skill 环境必备； 4. **边界声明**——注册表越挤越重要，写之前先看邻居； 5. **示例前置与档位语义**——锦上添花，命令型工具值得加。 一句话收束：正文决定你的 Skill 干得好不好，描述决定它有没有机会上场。四百件 Skill 同台的环境里，胜负在模型读到你第一行字的那半秒钟就分完了。 ## 参考来源 1. [anthropics/skills](https://github.com/anthropics/skills) — 官方 Skills 仓库，SKILL.md 结构与 frontmatter 规范的权威出处 2. [skills.sh](https://skills.sh) — Skills 生态站，可查社区 Skill 热度榜单 3. 本机 Claude Code 运行时注册表 — 本文九段描述原文与装机清单普查均取自当前环境的真实 Skill 注册信息 > [!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 等场景全覆盖。