# 写法第六遍：门没开，课照讲 **栏目**：Skills 生态观察 · 第 8 轮(设计模式提炼特辑) **日期**：2026-10-05 ## 本轮概况 按排期，第 8 轮该做的是全栏最“教人”的一期：从本周最热门的 Skill 里提炼 SKILL.md 的写法模式，让读者照着写出自己的第一个 Skill。原计划是抓本周榜单、选一件头部作品、把它的 SKILL.md 逐段拆开来讲。 结果和第五遍一样：五条采集通道全部保持关闭，实时素材零到账。榜单拿不到，热门件的原文拿不到，连一篇可交叉验证的页面都拿不到。 所以这一期换一种讲法：**不引榜单、不报星数、不拆具体某一件，只讲不依赖任何实时数据也成立的东西**——SKILL.md 这门手艺本身的通用写法。这些模式来自 Skill 机制公开的设计约定，属于“学会了到哪个仓库都适用”的地基部分。等通道重开，再用实测数据回头校验。 以下正文，全部可以空手验证：你只需要一个文本编辑器，和一个装着 Claude Code 的终端。 ## 一、先搞清楚：你写的东西是怎么被用到的 写 Skill 之前，得先知道它的生命周期。一个 Skill 从躺在你磁盘上到真正干活，中间发生的事情其实很短： ```mermaid flowchart TD A["用户提问"] --> B{"门牌命中?"} B -->|是| C["读入正文"] B -->|否| D["保持静默"] C --> E{"正文够用?"} E -->|够| F["直接作答"] E -->|不够| G["按需读参考文件"] G --> H["必要时运行脚本"] H --> F ``` 这张图里有三个对写作者至关重要的后果： **第一，门牌不中，一切免谈。** 模型平时看到的只是每个 Skill 的元信息(名字加一句描述)，正文根本不在它的注意力里。你的 Skill 能不能被想起来，完全取决于那句描述写得准不准。这决定了后面所有模式里，description 是优先级最高的一个字段。 **第二，正文是按需加载的。** 只有被命中之后，正文才会进入上下文。所以正文写多长，直接影响每次触发的成本——写一千行废话，等于每次触发都先罚一次税。 **第三，参考文件和脚本是第三层。** 正文里可以指向同目录下的其他文件，模型在需要时才去读。这是官方机制里明确的分层设计，也是“渐进披露”这个词的来源：门牌一句话，正文一页纸，细节一柜子，按需开柜。 理解了这三层，九条写法模式就有根了——**它们全都是围绕“怎么让第一层被命中、让第二层够轻、让第三层扛重活”展开的。** ## 二、九条写法模式 ### 模式一：description 是唯一的门牌，写“什么时候用”而不是“这是什么” 新手最常犯的错，是把 description 写成产品简介：“这是一个帮助您处理 PDF 的技能。” 这句话的问题在于：模型选 Skill 时问的不是“有个叫 PDF 的东西吗”，而是“**眼前这个任务，该派给谁**”。所以门牌要写成派工单的口吻，把触发场景直接喂给它。通行的好写法是两段式：一句说明它做什么，再一句用“当用户要……时使用”的句式列出触发条件，并且把领域词(文件格式、动作、场景)写实、写全。 还有一个容易忽略的细节：描述要用第三人称陈述句，而不是对模型喊话的口吻。门牌是给“选派者”看的档案卡，不是给执行者看的命令书——命令书是正文的活。 **自查方法**：把你的 description 单独贴出来，遮住 Skill 名字，让同事猜“什么情况下会想到它”。猜不中的触发场景，就是没写进去的场景。 ### 模式二：渐进披露——正文当目录页，别当百科全书 机制允许正文引用同目录的参考文件，这就给了你一个清晰的预算原则：**正文控制在“一页纸”量级，细节全部外置**。 实操上的分工是： | 层 | 放什么 | 理想体量 | |---|---|---| | 门牌(description) | 是什么 + 何时用 | 一两句话 | | 正文(SKILL.md) | 工作流、核心规则、文件地图 | 几十行到百行级 | | 参考文件(reference.md 等) | 字段表、完整示例、边界情况 | 不限 | | 脚本(scripts/) | 确定性逻辑 | 不限 | 正文里最重要的一节，反而是“文件地图”——告诉模型“遇到什么情况去读哪个文件”。这就像一本书的目录：模型先翻目录，再决定翻哪一章。没有地图的正文，模型只能整柜子翻，又慢又容易漏。 ### 模式三：把工作流写成编号工序，而不是写成散文 模型执行指令时，编号步骤的遵守率远高于大段落。同样一套流程，“首先你要……同时注意……另外别忘了……”是散文；“1. 做甲。2. 做乙。若乙失败，转第 4 步。”是工序。 工序化的两个加分项： - **分支显式化**：条件判断单独成行，“若 X 存在则走第 3 步，否则走第 5 步”，别让模型自己从句子里提炼控制流。 - **每步一个动词开头**：读取、生成、校验、输出。动词开头的句子天然就是指令。 这也是为什么很多成熟 Skill 读起来“不像文章，像作业指导书”——不是文风问题，是设计选择。 ### 模式四：祈使句写正面规则，反例清单写红线 正面规则用祈使句(“始终先备份原文件”)，红线用显式的否定清单("Never:在未确认路径前删除文件")。两者分开列，混在一起会互相稀释。 反例清单的价值经常被低估。模型犯错的方式是可预期的：它不是随机犯错，而是在特定场景下系统性地走捷径(比如跳过确认直接删文件、比如生成文件前不检查目录是否存在)。**把你预料到的走捷径方式，一条条写成禁止项**，比多写十句正面鼓励都管用。 这也是官方示例里反复出现的结构：一个“必须做”清单，配一个“禁止做”清单，两清单对仗。 ### 模式五：能交给脚本的，别交给嘴 确定性逻辑(格式转换、字段校验、批量重命名)写成脚本，正文里只写“何时调用哪个脚本、参数是什么”。判断性逻辑(这个需求合不合理、这个翻译自不自然)才留在提示词里。 原因很朴素：脚本执行一百次结果一致，自然语言指令执行一百次会漂移。凡是“这件事有唯一正确答案”的部分，都不该靠模型每次现场发挥。 配套写法：每个脚本在正文里给出一行说明——功能、输入、输出、调用示例。模型是照着说明书调用脚本的，说明书缺失时它会猜测参数，猜测就是事故来源。 ### 模式六：写明输出契约 Skill 最终总要交付点什么：一个文件、一段报告、一次提交。输出契约就是把交付物写死：**格式、路径、命名规则、完成后要报告什么**。 “把整理结果输出成 Markdown”是弱契约；“输出到 `output/<日期>/` 目录，文件名为 `<主题>-<日期>.md`,完成后向用户报告文件路径和条目数”是强契约。强契约的好处不止于规范：它让模型在收尾时有明确的“完成判定”，不至于做一半就交差。 ### 模式七：给 Skill 配一条自检闭环 成熟的 Skill 几乎都有一个收尾步骤：干完活，自己验收。写法很简单，在工序最后加一步： > 输出完成后，对照以下清单逐项自查；任何一项不满足，回到对应工序修正后再交付。 清单内容与输出契约一一对应。这一步成本几乎为零，但它把“做完”和“做对”区分开了。这与本栏此前观察过的多件头部作品的共性一致：**流程件的尾部，都挂着一张验收单。** ### 模式八：命名与瘦身——目录即文档 目录结构本身就该能读出分工，通行约定是： ``` my-skill/ ├── SKILL.md # 门牌 + 正文(目录页) ├── reference.md # 细节:字段表、完整示例 ├── examples/ # 输入输出样例 └── scripts/ # 确定性脚本 ``` 两个纪律：一，文件名自解释，`reference.md` 胜过 `notes2.md`;二，正文里引用的每个文件都必须真实存在——指向空路径是新手事故榜第一名，模型读了空路径要么报错要么脑补，两个都是灾难。 ### 模式九：一个 Skill 只做一件事 最后一条是纪律也是止损阀。看到“我还能顺便支持 XX 吗”的念头时，正确动作是开一个新 Skill,而不是往正文里追加一节。 判断标准借用Unix 哲学：**如果一个 Skill 的 description 需要用到“以及”“同时”“还支持”，它就该被拆了。** 多事之门牌在派工时互相污染——描述越贪，每个场景的命中率越低，这是机制层面的惩罚，不靠自觉。 ## 三、最小可运行模板 把九条模式压进一个骨架，这就是你的第一个 Skill。改掉大写占位符就能用： ```markdown --- name: my-first-skill description: 做什么(一句话)。当用户要 <触发场景 A、B、C> 时使用。 --- # My First Skill ## 概述 本技能用于 <目标>。适用于 <场景>,不适用于 <边界>。 ## 工作流 1. 读取 <输入>,确认 <前提>。 2. 执行 <核心动作>。若 <异常>,转第 4 步。 3. 生成交付物,转第 5 步。 4. 按 <降级策略> 处理后,转第 3 步。 5. 对照下方清单自查,全部通过后向用户报告。 ## 输出契约 - 路径:output/<日期>/<名称>.md - 格式:<结构说明> - 完成后报告:文件路径 + 关键统计 ## 禁止事项 - Never: <最危险的走捷径方式 1> - Never: <最危险的走捷径方式 2> ## 参考文件 - 细节字段与完整示例见 reference.md - 批量处理调用 scripts/run.sh(输入:<格式>;输出:<格式>) ## 自查清单 - [ ] 交付物存在于约定路径 - [ ] 格式符合输出契约 - [ ] 未触碰禁止事项 ``` 装进 `~/.claude/skills/my-first-skill/` 目录后重启会话，说一句触发场景里的话，看它是否被命中——**第一轮测试只测“命中”，第二轮才测“干对”**，两轮分开，问题定位快一倍。 ## 四、九条模式对照表 本轮没有实测对象，评测表改为模式自身的性价比对照(价值 = 对触发/执行成功率的贡献；成本 = 写作与维护负担)： | 模式 | 新手价值 | 维护成本 | 最常见死法 | |---|---|---|---| | 一 门牌写触发场景 | ★★★★★ | 低 | 写成产品简介 | | 二 渐进披露 | ★★★★★ | 中 | 正文塞成百科 | | 三 工序化 | ★★★★ | 低 | 写成散文 | | 四 反例清单 | ★★★★ | 低 | 只写正面要求 | | 五 脚本化 | ★★★★ | 中 | 让模型现场发挥确定性逻辑 | | 六 输出契约 | ★★★★ | 低 | 交付物含糊 | | 七 自检闭环 | ★★★ | 低 | 忘了写 | | 八 目录即文档 | ★★★ | 低 | 引用空路径 | | 九 只做一件事 | ★★★★ | — | 描述里出现“以及” | 新手优先级 Top 3:**门牌、渐进披露、输出契约**。门牌决定“用不用得上”，披露决定“用得起吗”，契约决定“交付算不算数”。其余六条可以在第一版跑通后再迭代。 ## 五、结语 第五遍挖写法时，门锁着，交了白卷。第六遍门还是锁的，但这回把课空手讲完了：九条模式、一张生命周期图、一个能直接抄的模板——全部不依赖本周的榜单与星数。 这些内容的回验方式也现成：等通道重开，拿本周头部件的 SKILL.md 逐条对照，看这九条在真实高分作品里的命中情况；命中不全的，补模式；互相冲突的，改模式。写法这门课，本来就该在“讲义”和“标本”之间来回对表。 ## 参考来源 本轮五条采集通道全部关闭，无任何实时抓取结果，以下为任务指定的稳定生态入口，本文未从中取数，仅作后续验证入口备查： 1. [anthropics/skills](https://github.com/anthropics/skills) — 官方 Skills 仓库，通道重开后首批回验对象 2. [skillsmp.com](https://skillsmp.com) — Skills 聚合目录，热度排序数据源 3. [mcpservers.org/agent-skills](https://mcpservers.org/agent-skills) — 官方与社区精选目录 4. [skills.sh](https://skills.sh) — Skills 生态榜单站，回验“本周热门”用 5. [skillsdirectory.com](https://www.skillsdirectory.com) — 带安全评级的目录，后续横评参考 > [!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 等场景全覆盖。