# 八轮拆完，抄下这份写法总图 ## 概述 本系列到这一轮是第8轮，按既定节奏，这一轮不追单件热度，改做总装：把前七轮拆过的几十件——官方全家桶、superpowers、gstack、mcp-builder、stop-that-shit、huashu-nuwa 等等——放回同一张解剖台上，提炼它们反复出现的 SKILL.md 写法手法。核心发现一句话：**好件的 SKILL.md 不是说明书，是一份合同**。合同有八条条款，其中四条是老面孔（门牌、分层、外置、让路），此前各轮分别拆过；另外四条此前从未被系统讲过——它们全是「出事了怎么办」的条款，本文称之为防御式写法，是本次的新增量。文末给出最小骨架模板，照抄即可落地你自己的第一件。本篇与此前《写Skill前先过的四道门》（写前决策）不重叠：那篇管「要不要写」，这篇管「怎么写」。 ## 一张总图：一件 Skill 的解剖学 先看全貌。拆开任意一件成规模的 Skill，正文里反复出现的条款可以归成三层八格： ```mermaid flowchart TD S[一件Skill] --> A[门牌层] S --> B[正文层] S --> C[资源层] A --> A1[门牌合同] A --> A2[邻居让路] B --> B1[分层披露] B --> B2[先划禁区] B --> B3[留退路] B --> B4[自证清白] B --> B5[把坑刻成碑] B --> B6[交付边界] C --> C1[脚本外置] ``` 门牌层和资源层此前已有专文（触发工程、暗字段、造件机），本文只做索引；正文层的四格防御条款是本轮重点。 ## 老面孔四格：快速过账 **门牌合同**——description 字段是全件唯一的广告位，写法是双句式：前半句说「我是干什么的」，后半句说「什么情况下该叫我」。此前「一个字段定生死」整篇讲的就是它，此处只补一个总图视角：门牌写砸的件，功能再好也是死件，因为宿主根本不会在正确的时机把它装进上下文。 **分层披露**——门牌之下，正文只放「总是需要的」，其余全部下沉到附属文件，用到才读。官方 docx 拆解时看到的「门后还有一道门」就是这一格的教科书案例：正文极短，真正的操作手册藏在正文引用的子文档里。 **脚本外置**——确定性逻辑不写成提示词，写成脚本，SKILL.md 只负责告诉模型「何时调、怎么调」。mcp-builder 和 xlsx 的拆解都验证过同一条规律：提示词负责判断，脚本负责执行，两者混写必出事故。 **邻居让路**——description 里主动写「如果用户要的是 X，不要用我，去找某某件」。内建四件横评里见过官方件互相让路的原文。这一格的本质是：Skill 生态里你的对手不是用户的需求，是同机其他的件。 下面是正餐。 ## 新面孔四格：防御式写法 ### 第一式：先划禁区 **定义**：正文开头不是「我能干什么」，而是「我不能干什么」。 绝大多数初学者写 SKILL.md，第一段是热情的自我介绍。拆了几十件之后看下来，成手的第一段恰恰相反——先交代什么情况不该触发本件。官方 webapp-testing 这类测试件的通行写法是：先声明「本件只管网页、不管桌面应用」，再开始讲流程。这一格的价值在于成本几乎为零：十行以内的负面清单，换来的触发精度提升是全局性的。宿主模型选件时做的是语义匹配，负面条款和正面条款一样参与匹配——你写下「不管桌面应用」，模型在桌面应用场景就不会错拿你。 **示意写法**（自拟示例，非任何仓库原文）： ```markdown ## 何时不要用本件 - 目标是生成全新文档（而非修改已有文档）→ 用 xxx 件 - 输入是图片而非文本 → 直接拒绝，不要尝试 - 文件超过 10MB → 走分片路径，见「留退路」一节 ``` **反面写法**：把禁区藏在正文最后一节的「注意事项」里。禁区放最后等于没写——模型的注意力预算在正文头部，尾部条款的遵从率显著衰减。 ### 第二式：留退路 **定义**：为每一个关键动作写明「主路径走不通时的降级路径」。 此前拆官方 docx 时反复看到同一种结构：先尝试直接改 XML，改不动就退回重建文档；先试流式解析，解析失败就退回整读。这就是退路条款。它要防的是模型的一个天然缺陷：**模型遇到报错时的默认行为是硬着头皮重试原路径**，而重试三次同一报错是装机用户最常见的一星差评来源。退路条款把「换路」这个决策前置写死，模型不需要现场发明 plan B。 写退路有一条纪律：**退路必须是不同的路，不是同一条路多走几遍**。写「如果失败请重试」等于没写。 **示意写法**： ```markdown ## 失败降级 1. 主路径：python scripts/patch.py 原地修改 2. 若报"格式不支持"：不要重试，改走 scripts/rebuild.py 整体重建 3. 若重建也失败：停下来，向用户报告卡点，禁止静默输出残缺结果 ``` 注意第 3 条——退路的尽头必须是「向人举手」，不是「假装完成」。这是下一式的前置。 ### 第三式：自证清白 **定义**：写明「干完活之后，用什么判据证明活没干砸」，判据必须可执行。 这一式是防御四式里最值钱的一格。把工程纪律写成流水线的 superpowers，整件的核心资产就是它——纪律的落点不是「怎么干」，而是「干完必须验」。用户对 Agent 产出的信任危机，八成来自「它说做完了，打开一看没做完」。自证清白条款把验收标准从用户的脑子里搬进 SKILL.md： **示意写法**： ```markdown ## 完成判据（全部满足才算完成） - 脚本退出码为 0 - python scripts/validate.py 输出 PASS - 抽查开头/中间/结尾三处，内容与需求一致 不满足任何一条：回到「失败降级」，禁止口头宣布完成 ``` 反面写法是口号式自检：「请仔细检查确保质量」。「仔细」和「确保质量」都是不可执行的词，模型无从落实。判据必须是脚本退出码、文件存在性、格式校验这类二值断言。 ### 第四式：把坑刻成碑 **定义**：把该赛道已知的具体坑，写成硬禁令清单，一坑一行，不给解释余地。 这一格在图类画图件里最密集：禁用某种不支持的图型、一条语句只许画一条边、标签长度上限、特殊字符黑名单——每一条背后都是一次真实的报错。它的原理与通用提示词工程里的「负面清单」不同：**这里禁的不是模型的坏习惯，是外部工具的物理限制**。模型不知道 mermaid 10 砍掉了哪些图型，你替它踩过的每一次报错，都应该变成一条禁令存进 SKILL.md，否则下一个会话从零再踩一遍。 写法纪律有两条：一，一行一坑，禁止写成段落——段落里的禁令会被模型平均用力，清单里的禁令才会被逐条核对；二，禁令后面跟一句「改用什么」，只堵不疏的禁令会逼着模型现场发明更糟的替代方案。 **示意写法**： ```markdown ## 硬禁令（每条都是真实报错换来的） - 禁用 quadrantChart（中文标签必然词法报错）→ 改用表格 - 一行只写一条边，禁止链式 A-->B-->C - 标签含斜杠/冒号时必须加引号 ``` ### 附：交付边界 防御式写法还有个收尾条款：写明本件**产出什么文件、明确不产出什么**。「不产出文件：思维件六件横评」记录过一个现象——一批件的价值恰恰在于「只改变想法、不留文件」，如果 SKILL.md 不把这个边界写死，模型会热心地多生成一份没人要的 markdown。产出边界写一行，省掉用户每次的「删掉你多写的那个文件」。 ## 模式采用度对照表 把八格放在一起看，按「抄写价值」（照抄收益）与「上手成本」（写好的难度）两个维度归档。代表件均为本系列此前拆过的件，星级是定性复盘，不是量化实测： | 模式 | 代表参照 | 抄写价值 | 上手成本 | 备注 | |------|---------|:---:|:---:|------| | 门牌合同 | 官方全家桶各件 | ★★★★★ | 低 | 一件生死所系，必写 | | 邻居让路 | 官方内建件 | ★★★★☆ | 低 | 机器上件越多越重要 | | 分层披露 | docx（门后有门） | ★★★★☆ | 中 | 件超过200行必须做 | | 脚本外置 | mcp-builder、xlsx | ★★★★★ | 高 | 要会写脚本，收益最大 | | 先划禁区 | webapp-testing 类 | ★★★★★ | 低 | 十行成本，全局收益 | | 留退路 | docx（改XML/重建） | ★★★★☆ | 中 | 退路必须换路，不许重试 | | 自证清白 | superpowers | ★★★★★ | 中 | 防御四式之首 | | 把坑刻成碑 | 图类画图件 | ★★★★☆ | 低 | 踩一坑刻一坑 | | 交付边界 | 思维件六件 | ★★★☆☆ | 低 | 一行成本 | 规律很明显：上手成本低的几格（门牌、禁区、禁令、边界）恰恰是采用率最低的——因为它们不炫技，写起来没有成就感。而拆到行之后看，**好件和坏件的差距，八成在这几行「不体面」的条款里**。 ## 最小骨架：照抄即用 最后给一个把八格全部落进去的骨架。说明：这是模式拼装的教学骨架（自拟），不是任何真实仓库的文件；也刻意不带你现场造一件——不想手写的读者直接用官方造件机 skill-creator，此前已有拆解，本文给的是读懂它产出物所需要的眼力。 ```markdown --- name: my-first-skill description: 做 X 的一件事。当用户提到 Y、Z 场景时使用； 若用户要的是 A 场景，不要使用本件（用 B 件）。 ← 门牌合同 + 邻居让路 --- # My First Skill ## 何时不要用本件 ← 先划禁区 - （负面清单，3-5条） ## 流程 ← 正文只放总流程 1. （每步一句话；细节下沉到 reference/ 子文档） ← 分层披露 2. 调用 scripts/run.py，禁止手工等价操作 ← 脚本外置 ## 失败降级 ← 留退路 1. 主路径失败 → 换 B 路（禁止原路重试） 2. B 路也失败 → 报告卡点，禁止静默输出 ## 硬禁令 ← 把坑刻成碑 - （一坑一行，每条注明改用什么） ## 完成判据 ← 自证清白 - （可执行的二值判据，全部满足才算完成） ## 交付边界 ← 交付边界 - 只产出：xxx；不产出：额外总结文档 ``` ## 排行榜 **最好抄的三式**（收益/成本比最高）： 1. 把坑刻成碑——你在自己赛道里踩过的每个报错都是独家资产，别人抄不走 2. 先划禁区——十行以内，触发精度立竿见影 3. 交付边界——一行字，消灭最招人烦的过度产出 **最容易写砸的三个坑**： 1. 门牌写成正文书摘——description 里塞满功能细节，触发反而失准（细节该在正文，门牌只管叫号） 2. 退路写成「失败请重试」——同一条路多走几遍不是退路，是原地罚站 3. 自检写成口号——「仔细检查」不可执行，退出码和校验脚本才可执行 ## 参考来源 1. [anthropics/skills](https://github.com/anthropics/skills) — 官方 Skills 仓库，门牌/分层/外置写法的基准样本 2. [skills.sh](https://skills.sh) — Skills 生态站，装机与热门榜单 3. [skillsmp.com](https://skillsmp.com) — 2300+ 件的可搜索目录 4. [mcpservers.org/agent-skills](https://mcpservers.org/agent-skills) — 官方与社区精选件目录 5. 本系列前七轮拆解档案 — docx/pdf/pptx/xlsx 全家桶、superpowers、gstack、mcp-builder、stop-that-shit 等单件拆解，为本文复盘素材 > [!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 等场景全覆盖。