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