# 官方模板拆开：写件六条心法直接抄 ## 概述 这是本系列第 8 轮定期拆解，轮到「设计模式提炼」：不追新星、不比榜单，而是回答一个更基础的问题——**第一批想自己写件的人，第一份 SKILL.md 该怎么落笔**。本期没有去追某个爆红新件，而是把拆解对象换成了所有人都拿得到的那份「官方样板间」：anthropics/skills 样例库。所有例证均来自本机装机盘的实测目录清单（官方样例库、官方插件市场、Obsidian 插件市场、自建件目录四处的真实路径），成稿期为离线环境，文中不采信任何未能核验的星标与下载量。核心发现一句话：**官方写件的全部秘密，不在文采，在结构——门牌、三层、护栏、禁令、例子、家族，六条心法就够写完第一件。** ## 先看样板间：实测目录清单 写件之前先看官方自己怎么住。本期在本机装机盘里实测到的四处「官方产地」，路径真实可复现： | 产地 | 实测内容 | 对写件人的价值 | |------|---------|---------------| | anthropic-agent-skills 样例库 | 16 个件 + 1 个 template/ 目录（docx、pptx、xlsx、pdf、brand-guidelines、mcp-builder、skill-creator、slack-gif-creator、theme-factory、webapp-testing、internal-comms、doc-coauthoring、algorithmic-art、canvas-design、frontend-design、web-artifacts-builder） | 官方写法的「一题一解」全集 | | 同库 template/ 目录 | 官方自带的 SKILL.md 模板位 | 第一件的起手骨架就在这 | | claude-plugins-official 插件市场 | plugin-dev 插件下挂着 7 个「教 Claude 造件」的件：skill-development、plugin-structure、command-development、hook-development、agent-development、mcp-integration、plugin-settings | 官方把「怎么写件」本身也做成了件 | | 本机自建区（~/skills/） | course-video-maker 家族（含 -zh / -en / -link 变体）、ericsson-ppt-writer 三个版本、knowledge-card-pro、video-remix、workflows/gsma-spec-to-video、_archived_arxiv-to-video | 一个真实学习者的「作业本」，家族化痕迹完整 | 三处官方产地 + 一处自建区，拼出了同一件事：**件不是文章，是带门牌的工序包**。下面六条心法，全部从这套样板间里提炼。 ## 心法一：门牌比正文重要——description 是路由器 一件 Skill 的生死，九成系于 frontmatter 里那两行 YAML：`name` 和 `description`。本系列此前拆过的结论可以直接复用——描述写不好，件装了也没人叫（见旧文《一段描述，决定 Skill 生死》《装上没人叫：补上装配线第九站》）。 写法上有三条硬规矩： 1. **第三人称**。description 是写给调度器看的路由表，不是写给用户的广告词。「This skill should be used when...」是官方样例库的标准起手式，中文场景就写「当用户提到……时使用」。 2. **触发词要写用户嘴里的原话**。用户会说「写周报」，不会说「进行周度工作汇总的结构化整理」。门牌上刻的是街坊的叫法，不是你的学名。 3. **边界写进门牌**。什么时候用、什么时候明显不该用，一句话讲清。官方 plugin-dev 里的那排「造件教学件」每件管一窄条（command-development 只管斜杠命令，hook-development 只管钩子），门牌互不重叠，所以从不误触发。 反例很好认：一件描述写着「提升你的工作效率的全能助手」——这等于在一条街上挂了块空白招牌，调度器只能跳过它。 ## 心法二：三层渐进披露——别把正文写胖 官方机制是三层加载，一张图说清： ```mermaid flowchart TD A["用户说出需求"] --> B{"匹配门牌
description"} B -->|命中| C["载入正文
SKILL.md"] B -->|未命中| D["件不启动
零成本待机"] C --> E["正文够用
直接干活"] C --> F["复杂任务
按需读包裹文件"] F --> G["脚本
可执行护栏"] F --> H["参考文件
模板与清单"] G --> I["产出交付物"] H --> I E --> I ``` 第一层永远在场：name + description，几十个 token，负责「要不要叫醒这件」。第二层按需加载：SKILL.md 正文，官方建议控制在五百行以内，负责「怎么干」。第三层同样按需：正文里用相对路径引用的脚本、模板、参考文件，负责「干细活」。 本系列拆官方 docx 件时的发现是这条心法最好的注脚：正文只留主干，把各类边角场景（表格、修订、样式丢失）全部下沉到附属参考文件，用到哪张翻哪张。**正文是菜单，不是满汉全席。** 第一件最容易犯的错，就是把毕生所学全部塞进正文——结果门牌再准，模型读完正文，上下文窗口已经被你吃掉半窗。 ## 心法三：能写成脚本的，别写成散文 样板间里最强的件，正文往往短得可疑，真正干活的在 scripts/ 目录里。逻辑很朴素：模型用自然语言做确定性操作，每一步都是掷骰子；同样的操作固化成脚本，就变成了调用一次、执行一次、结果确定。 判据一条：**这件事的「正确答案」是否唯一？** 是，就写脚本；不是，才值得用文字教。字体转换、文件解包重打包、格式校验、批量重命名，全是脚本的活；而「怎么把话写得不像 AI」这种没有唯一解的，才是正文的活。第一件写作者常有的误区是反过来：把 pip install 该干的事写成三行温馨提示。官方样例库里带脚本的件，等于在正文里放了一句话：「别劝我做，直接调我做。」 ## 心法四：禁令要大写——踩过的坑刻成 CRITICAL 本系列拆 docx 件时留下过一个标题级的结论：坑都刻成了 CRITICAL。官方写法的独门之处在于，**错误不是被修复掉的，是被铸进正文里的**：某类操作必然导致文件损坏，就写成一行大写禁令，放在流程步骤旁边，让模型在走到那一步时必然撞见。 给写件人的启示是：禁令不是防御性废话，是你的「事故存档」。第一版可以没有禁令——因为你还没踩坑；但每次实测翻车，回来加一行 `CRITICAL:` 或 `NEVER:`，这件就开始积累别人抄不走的部分。禁令要具体到动作（「永远不要直接编辑 X，先运行 Y」），不要写「请务必小心」（模型不知道「小心」是什么操作）。 ## 心法五：一对好坏例子，胜过十行形容词 官方审美件（frontend-design，即本系列拆过的「降俗清单」）的路数：不堆形容词，直接给对比——什么叫俗，什么叫不俗，各来一段。这背后是提示词工程里最老实的原理：模型的模仿能力远强于它的理解能力。 正文里的「例子区」因此应该是每件的标准配置：**一个好输出 + 一个坏输出，各配一句为什么**。写周报件就放「合格周报」和「被打回的周报」；画图件就放两张图的描述差异。第一件写作者最容易写成产品文案：「输出应当专业、简洁、有洞察力」——这三个词模型各自有五百种理解，其中四百种不是你要的。 ## 心法六：家族化分工——变体后缀与流水线拆件 这是本期最有意思的发现，因为它不在官方文档里，而在装机盘的自建区里。实测本机目录：同一份 course-video-maker，住着 -zh、-en、-link 好几个变体；ericsson-ppt-writer 有三个版本并存；隔壁 pcap 赛道（generator / analyzer / modifier）则是一**条流水线拆成三件**，每件管一段。 ```mermaid flowchart TD S["第一步 定边界
只解决一件事"] --> T["第二步 写门牌
第三人称加触发词"] T --> U["第三步 写正文
五百行以内"] U --> V["第四步 埋护栏
脚本与模板入仓"] V --> W["第五步 刻禁令
踩过的坑变大写"] W --> X["第六步 实测触发
换三种说法试门牌"] ``` 两条家族化路线，各有适用： - **变体后缀**：同一工序，参数不同（语言、平台、格式）。拷贝、改门牌、改参数区，三步出一件。适合场景稳定、只换「配置」的件。 - **流水线拆件**：一条长链路（生成→分析→修改），每段一个件。好处是每件门牌窄、触发准、坏一段不连坐。适合步骤间有明确交接物的链路。 判断标准也简单：如果两件事永远一起被需要，做成一件；如果经常只要其中一件，拆开。 ## 第一件 Skill：可直接抄的最小模板 以下是本文自写的教学模板（非官方文件引用），覆盖上述六条心法，保存为 `~/.claude/skills/weekly-report-writer/SKILL.md` 即可生效： ```yaml --- name: weekly-report-writer description: 把本周的 git 提交记录、会议记要与零散笔记整理成一份结构化周报。当用户提到「写周报」「整理本周工作」「汇总这周干了什么」时使用。不适用于 OKR 制定或绩效自评。 --- ``` ```markdown # 周报整理 ## 何时用 / 何时不用 用：有原始素材（提交记录、笔记、记要），需要产出一页周报。 不用：用户只要一句口头总结时，直接回答，不要启动本流程。 ## 工作流程 1. 收集：向用户确认素材来源，逐个读取。 2. 归并：按「进展 / 风险 / 下周计划」三类归并，同一事项只出现一次。 3. 排序：进展按对目标的影响排序，不按时间流水。 4. 产出：按 references/format.md 的模板输出。 ## 好例子 / 坏例子 好：「完成支付对账模块联调（阻塞项已清除）」——有结果、有状态。 坏：「持续推进支付相关工作」——无结果、无状态，被打回的典型。 ## 禁令 CRITICAL：素材里没有的进展，永远不要编造或脑补补齐，宁可留空并标注「待补充」。 ## 附件 - references/format.md：输出模板与字段说明 ``` 这份骨架里：门牌写了触发原话和排他边界（心法一），正文三十行以内、模板下沉到附件（心法二），流程步骤化（心法三雏形），禁令具体到动作（心法四），好坏例子各一条（心法五）。写完它，六条心法就全用了一遍。 ## 装好与实测三步 ```bash # 1. 从零写一件 mkdir -p ~/.claude/skills/weekly-report-writer $EDITOR ~/.claude/skills/weekly-report-writer/SKILL.md # 2. 或者先抄官方样板间 git clone https://github.com/anthropics/skills # 把想要的件目录整个拷进 ~/.claude/skills/ 即可 # 3. 或者用 CLI 搜市场上现成的架 npx skills find <关键词> ``` 实测校验只有一条铁律：**换三种说法去问**。用门牌上写的原话问一次，用同义但不同的表达问一次，再用一个不该触发的需求问一次。三次都对，门牌才算合格——这正是旧文《装上没人叫》给出的教训：件装好只是入库，被叫到才算上架。 ## 样板间定性评分表 以下为本系列观察视角的定性评分（1–5 星，非实测跑分）。本期在离线环境成稿，「社区活跃度」仅按官方维护状态与生态存在感定性给分，未采信任何下载量与星标数。 | 件 | 功能完整度 | 设计质量 | 实战效果 | 上手难度（越高越易） | 社区活跃度 | 一句话 | |----|-----------|---------|---------|---------------------|-----------|--------| | skill-creator | ★★★★★ | ★★★★★ | ★★★★☆ | ★★★★☆ | ★★★★★ | 造件的件，第一件的最佳副驾驶 | | docx | ★★★★★ | ★★★★★ | ★★★★★ | ★★★☆☆ | ★★★★★ | 护栏与禁令的教科书 | | frontend-design | ★★★★☆ | ★★★★★ | ★★★★☆ | ★★★★★ | ★★★★☆ | 例子打底心法的范本 | | webapp-testing | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★☆☆ | 把验收写进步骤的思路源 | | theme-factory | ★★★☆☆ | ★★★★☆ | ★★★☆☆ | ★★★★★ | ★★★☆☆ | 小而窄，适合当第二件练手 | | slack-gif-creator | ★★★☆☆ | ★★★★☆ | ★★★☆☆ | ★★★★★ | ★★★☆☆ | 短小样例，适合第一遍通读 | ## 推荐排行榜 **最值得先抄的三条心法**：① 门牌模式（成本最低、收益最大，五分钟见效）；② 三层披露（决定你的件是「快」还是「胖」）；⑤ 例子打底（决定输出质量下限）。 **最容易翻车的三条**：① 门牌写成广告词（件装了没人叫）；② 正文塞成百科（上下文被自己吃光）；③ 禁令写成「请小心」（等于没写）。 **样板间参观顺序**：先逛 template/ 目录拿骨架，再通读 slack-gif-creator 看短件长什么样，然后精读 docx 看护栏与禁令怎么铸，最后去 plugin-dev 那排「造件教学件」看官方如何给窄门牌分工。逛完这四站，再动手写自己的第一件，基本可以绕开前人踩过的所有大坑。 写件这件事，门槛从来不在代码，而在克制：门牌窄一点、正文瘦一点、禁令狠一点。官方样板间十六个件拆完，剩下的都是手熟。 ## 参考来源 1. [anthropics/skills — 官方 Skills 仓库](https://github.com/anthropics/skills) — 本文「官方样板间」的线上原产地，template/ 目录与各件源文件所在 2. [skills.sh — Skills 生态站](https://skills.sh) — Skills 生态热门榜单入口（本期离线成稿，未采信榜单数据） 3. [mcpservers.org/agent-skills — Claude Skills & Agent Skills Library](https://mcpservers.org/agent-skills) — 官方与社区精选件目录 4. [skillsmp.com — Skills 聚合市场](https://skillsmp.com) — 可搜索的 Skills 目录（2300+ 件，数据来自本期编辑简报） 5. 本机装机盘实测清单（`~/.claude/plugins/marketplaces/` 下 anthropic-agent-skills、claude-plugins-official、obsidian-skills 三处；`~/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 等场景全覆盖。