# 第一件Skill，九条套路写完 ## 概述 这是本栏第8轮观察。前七轮我们把货架上的件一件件往下拆，这一轮换个方向：把拆过的件重新摊开，不看它们「做什么」，只看它们「怎么被写出来」。本期不追新榜——样本与星数取自本刊拆件存档（检索数据截至2026年5月中旬，均在文中标注时点），因为这一轮的主角不是某一件新货，而是它们共用的那副骨架：SKILL.md。我们从存档里挑出六个结构最有代表性的件，提炼出九条反复被验证的写法套路，最后手把手带你写出并装上你的第一件Skill。 ## 先看清生态位置：写件正在变成新的「写README」 5月中旬的存档里有两个数字今天看依然成立：可检索的Skills从2025年中期的约50个涨到 **1,260+**（PopularAiTools Antigravity库，5月存档），而SKILL.md已经成了事实标准——同一个件可以跑在Claude Code、Cursor、Gemini CLI、Codex CLI等十多个平台上，存档里的planning-with-files更是宣称兼容40+种agent。 这意味着什么？意味着「会写SKILL.md」正在变成2026年的「会写README」：它不是炫技，是让你的工作方式能被任何AI终端复用的最小载体。README是写给人的，SKILL.md是写给模型的——写给模型的文档有一套完全不同的物理定律：它按需加载、靠描述匹配触发、每个字都占上下文。九条套路，全部从这三条物理定律推出来。 ## 先看懂骨架：一个SKILL.md的三层结构 拆开任何一个规范的件，内部都是三层： ```mermaid mindmap root((SKILL.md)) 前置声明 name 门牌 description 点火钥匙 正文 触发场景 工作流程 负面清单 示例 附属资源 references 深料 scripts 脚本 assets 素材 ``` - **前置声明（frontmatter）**：YAML格式的 `name` 和 `description` 两个字段。这是唯一永远被载入的部分——模型的每一次对话都会扫一遍所有已装件的描述，决定要不要「点亮」你这个件。 - **正文**：只有当件被命中后才会载入的部分。这里是你的操作手册。 - **附属资源**：`references/`（深度参考资料）、`scripts/`（可执行脚本）、`assets/`（模板素材）。只有正文引用时才会被读取。 这个三层结构就是官方所说的**渐进式披露（Progressive Disclosure）**——Skills 2.0架构的核心升级点（5月存档）。一句话总结它的经济学：**描述常驻、正文按需、深料再按需**。你的件被成百上千次扫描，但只有几次被真正展开，所以最贵的字要放在最常被扫描的那一行里。 ## 九条套路：从六个样本件里拆出来的规律 下面每条套路都标注了它从哪些件上归纳而来。样本清单：superpowers（12+子件的工作流全家桶）、planning-with-files（5月存档17,700+星）、humanizer（11,700+星）、impeccable（10,000+星）、Trail of Bits安全件集（4,100+星）、dev-browser（5,100+星，均见5月存档）。 ### 套路一：description写「何时用」，不写「是什么」 这是整个SKILL.md里杠杆率最高的一行。模型匹配触发靠的是description里的词和用户输入的词的重合度。新人最常见的写法是产品说明书式的： ```yaml description: 一个帮助处理图片的工具，功能强大。 ``` 这句话在匹配层等于空白。正确的写法是把**触发场景的动词和名词**塞进去： ```yaml description: 当用户需要裁剪、压缩图片、转换格式或给成批图片加水印时使用。处理PSD源文件时不要使用。 ``` 注意两个细节：用第三人称（描述是写给匹配器看的，不是写给用户看的广告词）；顺手写一句「何时不适用」，这一句能砍掉一大半误触发。本栏此前写过「一段描述，决定Skill生死」，那篇讲的是描述字段的生死权重，这里给的是施工方法：**名词要具体到用户会打出来的那个词**。用户想压缩图片时打的是「压缩」，不是「优化视觉资产」。 ### 套路二：正文是菜单，不是百科 正文有个行业软上限：**500行以内**。超过的部分不是删掉，是搬进 `references/` 目录，在正文里留一行「详细规范见 references/xx.md」。impeccable是这条套路的教科书样本——5月存档记录它的结构是**一个件文件挂20个命令和7份深度参考指南**，覆盖排版、色彩、空间、动效、交互、响应式、UX文案。它没有把七个领域塞进一个文件里，而是正文只放命令索引，深料按需展开。判断标准很简单：**这段话是每次执行都要读的，写正文；只有某一步才需要的，进references。** ### 套路三：写流程，不写知识 superpowers的12+个子件，名字本身就是一套流程动词表：brainstorming、writing-plans、test-driven-development、systematic-debugging、verification-before-completion（5月存档）。它教给我们的不是「懂TDD」，而是把工作方式写成**可勾选的阶段清单**：第一步做什么、产出什么、检查什么、不过关怎么办。模型执行清单的稳定性远高于执行散文式建议。你的件里最值钱的段落往往是一段： ```markdown ## 工作流程 1. 先读用户提供的原始材料，列出缺失项 2. 缺失项直接向用户提问，不要自行编造 3. 产出草稿后，逐条对照第1步的清单自查 4. 自查全部通过才输出 ``` ### 套路四：能写脚本就别写散文 凡是**确定性**操作——格式校验、批量重命名、字段抽取——写成 `scripts/` 里的一条命令，比三百字的描述更省token也更不会错。但要警惕反向过度：planning-with-files是全货架最红的件之一（17,700+星，5月存档），本栏拆它那次的结论恰恰是「零脚本存档术」——它的三文件法（任务计划、进度、发现）是纯**数据约定**，不需要任何脚本。所以这条套路的完整版是：**确定性操作进scripts，方法论约定留在正文，别为了显得工程化硬塞脚本。** ### 套路五：负面清单比正面指令更纠偏 humanizer（11,700+星，5月存档）基于维基百科的「AI写作特征」指南列了20多条**禁止出现**的痕迹：滥用的连接词、三段式排比、特定的AI惯用词。它的成功验证了一个提示工程的老规律：模型「不做某事」的自控力，来自你把「那件事」具体列出来。你的件里永远值得有一节「不要做」：不要跳过提问直接编、不要输出超过500字、不要在用户没给数据时使用示例数据冒充。 ### 套路六：一件一动词，拒绝全家桶 横评七轮下来反复出现的规律：宣称「什么都能干」的件，触发率反而低——因为描述里塞满了不同场景的词，匹配器无法判断它到底该什么时候上，而且一旦触发，大而全的正文会污染整个上下文。反例是正路：Trail of Bits的件集（4,100+星，5月存档）窄到只有静态分析这一件事，却拆成CodeQL、Semgrep、合约入口分析、变体分析等独立小件，每个件描述干净利落。**写第二件，好过写一件全能。** ### 套路七：示例三件套 在正文里给三个例子：一个**标准例**（正常输入长什么样）、一个**反例**（错误做法及为什么错）、一个**边界例**（极端输入怎么处理）。示例是唯一不会被误解的提示词——形容词可以被模型各自解读，输入输出对不会。三个例子加起来的token成本，往往低于一段 vain 的质量形容词。 ### 套路八：把验收写进件里 5月存档的趋势判断里有一条被低估的：「评估体系成熟，Skill Creator内置Evals、A/B测试，Skills质量可量化。」落到个人写件的层面，最小可行版就是在件尾写一节**完成定义**：这件活干完的标志是什么？例如「所有用户提供的条目都被处理」「输出里不存在未经来源的数字」。本栏拆官方测试件时说过它「短得可疑」——但方向是对的：没有验收条款的件，跑十次会有十种「完成」。 ### 套路九：门牌规则，撞名即失效 最后一条最机械也最致命：目录名用kebab-case且与frontmatter的 `name` 完全一致；description避免与已装件高度重叠。本机装机量已经三百多件（本栏写过这台机器装了384件），在这种密度下，描述写得含糊的件不是「用得少」，是**永远不会被点亮**——匹配器在几百个候选取最高分，含糊者恒为零分。 ## 样本件对比：按「教科书价值」评分 以下星级为本刊基于拆件记录的评定（维度与权重按本栏固定标准），星数数据为2026年5月存档时点，不代表当前： | 样本件 | 功能完整度(25%) | 设计质量(25%) | 实战效果(20%) | 上手难度(15%) | 社区活跃度(15%) | 综合 | |:---|:---:|:---:|:---:|:---:|:---:|:---:| | impeccable | ★★★★★ | ★★★★★ | ★★★★☆ | ★★★★☆ | ★★★★★ | **4.75** | | planning-with-files | ★★★★★ | ★★★★☆ | ★★★★★ | ★★★★★ | ★★★★★ | **4.70** | | superpowers | ★★★★★ | ★★★★★ | ★★★★☆ | ★★★☆☆ | ★★★★★ | **4.60** | | humanizer | ★★★★☆ | ★★★★☆ | ★★★★★ | ★★★★★ | ★★★★★ | **4.55** | | Trail of Bits skills | ★★★★★ | ★★★★☆ | ★★★★☆ | ★★☆☆☆ | ★★★★☆ | **4.15** | | dev-browser | ★★★★☆ | ★★★☆☆ | ★★★★☆ | ★★★★☆ | ★★★★☆ | **3.90** | 说明：设计质量一栏评的是「这个件值不值得当写作范文」。impeccable的命令+参考指南分层是渐进式披露的满分级样本；dev-browser设计上更偏功能实现（依赖MCP配合），当范文则一般。 ## 动手：写出并装上你的第一件 把九条套路一次用完。下面是一个完整的、可直接复制的首件模板——「会议纪要整理件」，一个真实高频、边界清晰的小场景： ```markdown --- name: minutes-fixer description: 当用户粘贴粗糙的会议录音转写稿或速记笔记，需要整理成 结构化会议纪要（含决议、待办、负责人）时使用。用户只是闲聊或要求 翻译时不要使用。 --- # 会议纪要整理件 ## 工作流程 1. 通读原始材料，列出缺失的关键信息（时间、与会人、决议、负责人） 2. 缺失项向用户提问确认，禁止自行编造 3. 按固定结构输出：会议信息 → 议题纪要 → 决议清单 → 待办表 4. 待办表每行必须包含：事项、负责人、截止时间（无则标注「未定」） ## 不要做 - 不要润色或改写发言人的原意 - 不要合并你不确定是否相同的事项 - 不要输出原始材料里不存在的数字 ## 示例 输入：「刚才和老王开会说下周三前把预算表交了」 输出待办行：| 预算表 | 老王 | 下周三 | ## 完成定义 - 原始材料中每一条可执行信息都出现在待办表中 - 输出中不存在来源不明的数字与日期 ``` 不到30行，九条套路占了七条：描述含触发动词与排除项（一）、流程化（三）、负面清单（五）、三件套示例（七）、验收条款（八）、kebab-case门牌（九）、按结构输出而非百科（二）。它不需要脚本（四），也只做一件事（六）。 安装只需两步——这就是全部的「装配线」： ```bash mkdir -p ~/.claude/skills/minutes-fixer # 把上面的内容存为 ~/.claude/skills/minutes-fixer/SKILL.md ``` 装完新开会话，说一句「帮你把这段会议录音转写整理一下」，观察它是否点亮。没点亮，回去改description里的名词，直到用户会打出的词和你写的词重合。 一条请求从进来到点亮你的件，链路是这样的： ```mermaid flowchart TD A["用户输入一句话"] --> B{"扫描已装件的描述"} B -->|命中触发词| C["载入正文与流程"] B -->|未命中| D["按普通对话处理"] C --> E{"正文是否引用附属资源"} E -->|需要| F["按需读取深料与脚本"] E -->|不需要| G["按流程执行"] F --> G G --> H["对照完成定义自查"] H --> I["输出结果"] ``` ## 新手首件翻车点排行 | 翻车点 | 症状 | 对应套路 | |:---|:---|:---:| | 描述写成广告词 | 装上之后永远不触发 | 套路一 | | 正文塞进全部知识 | 触发后上下文爆炸、响应变慢 | 套路二 | | 全家桶野心 | 什么都沾、什么都不精 | 套路六 | | 没有验收条款 | 十次执行十种「完成」 | 套路八 | | 与存量件描述撞车 | 被老件抢走触发 | 套路九 | ## 想抄作业？从这四个件开抄 按「最适合新手模仿的结构」排序（星数为5月存档时点）： 1. **planning-with-files** — 最小可行件：纯Markdown、零脚本、零依赖，看懂它就看懂了骨架。`git clone https://github.com/OthmanAdi/planning-with-files .claude/skills/planning-with-files` 2. **humanizer** — 负面清单范本：20多条禁止项怎么写得具体、可执行。`git clone https://github.com/blader/humanizer .claude/skills/humanizer` 3. **impeccable** — 渐进式披露范本：正文菜单+七份参考指南的分层教科书。`git clone https://github.com/pbakaus/impeccable .claude/skills/impeccable` 4. **Trail of Bits skills** — 参考资料重装范本：窄赛道深钻、references组织方式的满分级样本。`git clone https://github.com/trailofbits/skills .claude/skills/trailofbits` 九条套路背下来不如写一件：今晚花二十分钟，把你重复做过三次以上的某件小事写成SKILL.md，装上，看它第一次被点亮。 ## 参考来源 1. [本刊Skills生态第1轮评测存档（2026-05-16）](output/2026-05-16/skills-ecosystem-1600.md) — 本文所有星数、件结构与生态趋势数据的原始出处 2. [anthropics/skills](https://github.com/anthropics/skills) — 官方Skills仓库，frontmatter规范与skill-creator的权威来源 3. [OthmanAdi/planning-with-files](https://github.com/OthmanAdi/planning-with-files) — 零脚本三文件法样本件（本栏此前已专文拆解） 4. [pbakaus/impeccable](https://github.com/pbakaus/impeccable) — 渐进式披露分层结构样本件 5. [mcpservers.org/agent-skills](https://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 等场景全覆盖。