大多数人学写 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 被装载，正文才进入上下文；描述没命中，你正文写得再好都是死文档。
所以描述的工程目标只有一个：让模型在对的时机选中你，在错的时机放你过。少半句，该叫你不叫；多半句，不该叫你乱叫。九段在跑的描述，恰好展示了九种把这一行写到位的手法。
最值得精读的一段。它的描述分三个块：先一句功能总述（构建、调试、优化 Claude API 应用，顺带处理模型版本迁移），然后是两个关键词打头的清单：
anthropic / @anthropic-ai/sdk、用户问到 Claude API、用户在调缓存/思考/工具调用等特性、问到 prompt caching 命中率——四条进场条件，条条可被代码和对话直接验证；openai 或其他厂商 SDK、文件名带 *-openai.py、供应商中立代码、泛泛的编程/机器学习问题——四条退场条件。这是描述工程的最高配形态：正反两张闸门。TRIGGER 回答「什么时候必须叫我」，SKIP 回答「什么时候看起来该叫我但其实不该」。没有 SKIP 的描述，容易在「用户聊到 AI 编程」这种宽泛场景被误触发，一次误触发就是一次上下文污染。你写第一个 Skill 未必需要双闸门，但只要你的 Skill 与相邻领域有混淆可能，SKIP 那一行就值回票价。
这一段解决的是另一个致命问题：用户嘴里说的话，和机制术语对不上。它的描述里先声明「自动行为类请求（『从现在起每次……』、『每次都……』、『之前/之后……』）需要 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 的工具」，模型匹配不上，这单就漏接了。把目标用户最可能脱口而出的话术原文抄进描述，等于在路由表里预埋了同声传译。写法要点：例句要抄「用户会说的话」，不是「你能做的事」——这两者词汇分布完全不同。
它的描述里直接写明了参数档位的行为差异：低档位出报告「更少但置信度高」，高档位「覆盖更广但可能包含误报」，还写清了 --comment 会把结果发成 PR 评论、--fix 会直接动手修。
这一段的价值在于：调用方在发起调用之前就知道自己买的是什么。这不仅是用户体验，更是路由辅助——用户说「快速过一眼 diff」，模型看到「low = 少而准」，自然选中它并用低档跑。把可调参数的语义写进描述，等于给了模型一张点菜单，而不是让它点完才发现没有。
verify 的描述开头是功能（跑起应用、观察行为、验证改动真的生效），紧跟着一连串「Use when」：被要求验证 PR、确认修复有效、手动测试改动、看截图确认。它的姊妹篇 simplify 则专管另一件事——复用、简化、效率、抽象层级的清理——并且描述末尾专门补一句：它不做正确性 bug 排查，那归 code-review。
这就是边界声明的写法：不仅说清我做什么，还说清我隔壁那位做什么。在多个 Skill 共存的环境里，相邻 Skill 之间把分工写进各自的描述，是避免抢单、漏单的根本手段。这不是巧合，是设计职责——你在写描述时，应该抬头看一眼注册表里的邻居，主动在描述里划清地界。
run 的描述极短：启动并驱动本项目的应用，看看改动是否真的能跑。然后是触发场景清单：被要求 run、start、screenshot 应用，或确认改动生效。
它的可学之处在于动词覆盖面。同一个用户意图，有人会说「跑起来」，有人会说「启动」，有人会说「截个图看看」，有人会说「验证一下能不能用」。描述里把这些高频动词都点到，路由命中面就宽。新手最常见的错误是描述里只写自己选定的那个标准动词，而真实用户的话语里有五六个变体。
loop 的描述第一句就把完整用例写进去了：「按周期循环执行一个 prompt 或斜杠命令（如 /loop 5m /foo，默认间隔 10 分钟）」。
示例直接内嵌进描述，好处有两层：模型在决定是否调用时就能看到标准用法，调用后传参出错的概率大降；而且示例本身就是最强触发信号——用户输入长得像示例时，相似度匹配天然偏高。一行示例，顶三行功能说明。
deep-research 的描述里有一段罕见的内容：指导模型在调用之前先做什么。原文写明——如果问题太宽泛（比如「什么车值得买」却没说预算和用途），先问两三个澄清问题，再把精炼后的问题传进去。
这是描述的进阶用法：描述不只是路由信号，还可以携带「前置协议」。什么时候该反问、反问完怎么把答案织回任务——这些本该写在正文里的流程，有一小截被提到了描述层。适用于那些「问错就是大浪费」的 Skill：研究、下单、发消息，都属于此类。
这一段的描述一句话说完整个闭环：扫描你的历史会话记录，找出常见的只读 Bash 和 MCP 工具调用，然后把它们按优先级整理成允许清单，写进项目的 .claude/settings.json。
输入（transcripts）、加工（筛选常见只读调用）、输出（allowlist 写入指定文件），一句话里全齐。这种写法适合工具型 Skill：动词 + 对象 + 产物落点，三个要素一个不缺。模型对这种「有头有尾有交付物」的描述信任度最高，因为调用它的结果可预期。
回头看，九段描述有一个共同点：第一句永远是功能总述，二十个词以内，动词开头。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 清单 + 两条用户原话例句，二十分钟可以写完，已经胜过市面上大半只写功能不写触发的描述。
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 闸门，疑似沾边就进场。
五段式模板，直接抄：
---
name: weekly-report
description: 生成结构化的周报，从 git log 与任务清单提取本周产出。
TRIGGER when: 用户要求写周报、周总结、work log、本周汇报；
用户提供日期区间要求汇总工作内容。
例句："帮我写这周的周报""把这几个 commit 整理成周报"。
SKIP: 单纯的 git log 查看、与工作产出无关的日常总结。
---
（正文从这里开始：输入格式、输出格式、
处理步骤、边界情况，按操作手册的写法展开）
安装只需一个目录约定：
mkdir -p ~/.claude/skills/weekly-report
# 把上面的内容存为该目录下的 SKILL.md
# 重启会话后，新 Skill 即出现在注册表中
三个动作：总述句动词开头、TRIGGER 抄用户会说的话、与邻居划清边界。写完之后，用一句用户最可能说的话去测——模型叫不叫它，一分钟见分晓。叫了，描述合格；没叫，回来在描述里补上你刚才那句原话，再测。这个循环就是 Skill 描述工程的全部迭代方式，比读十篇教程都管用。
如果想要机器帮着起稿，本机注册表里的 skill-creator 就是干这个的：把需求说给它，它按官方规范生成骨架，你再回头按本文的五段式打磨描述。造件工具已经就位，缺的只是你对「那一行描述」的敬畏。
一句话收束：正文决定你的 Skill 干得好不好，描述决定它有没有机会上场。四百件 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 等场景全覆盖。