# 写Skill前先过的四道门——下笔之前的四个设计决定 ## 概述 ## 一、为什么先讲「下笔之前」：千星件也会死在第一步 这不是「懒得写简介」的小事。按 skill-creator 官方正文的口径（本栏目今日造件机拆解存档）：description 常驻上下文、是模型判断要不要加载你的件的唯一依据，正文写得再好，门牌不亮就没有然后。**「下笔之前」的决定，比下笔之后的文笔更早决定生死**——ffmpeg-skill 用千星证明了需求存在，也用空门牌证明了跳过决策的代价。 而决策的另一个极端也真实存在。装机目录实测（本栏目 gstack 开盖存档）：同一台机器上，defuddle 整件只有 1 个 SKILL.md，gstack 装下来超过 150 个文件、自带 CI 评测和卸载器——两件共用同一个安装姿势，体重差了两个数量级。中间还有 3 文件的脚配角件、5 文件的模板资产件、8 文件的小仓库件。**件的重量应该配任务的重量**，配错方向的两个死法都常见：把一句话能解决的事写成仓库（维护税先于价值到账），把需要脚手架的活写成一张名片（模型每轮都在裸奔现算）。 所以本期把「写你的第一个 Skill」重新排序：不是从打开编辑器开始，而是从回答四个问题开始。 ## 二、评测对比表 对比对象是装机目录实测的件型梯度五件加本周新架的命令壳一件。五维权重沿用本栏目固定口径：功能 25%、设计 25%、实战 20%、上手 15%（高分=易）、社区 15%。defuddle、openstoryline-use、long-running-agent、atlas、gstack 五件的文件数为 9 月 13 日装机目录 Glob 实测；其社区维度因未引外部数据从保守估※；ffmpeg-skill 正文通道未放行，功能与设计两维只能按公开快照信息预估※，社区维度有连续星轨迹佐证。 | Skill | 文件数（实测） | 功能 25% | 设计 25% | 实战 20% | 上手 15% | 社区 15% | 加权 | |---|---|:---:|:---:|:---:|:---:|:---:|:---:| | long-running-agent | 5 | ★★★★ | ★★★★★ | ★★★ | ★★★★ | ★★★※ | **3.90** | | openstoryline-use | 3 | ★★★ | ★★★★ | ★★★ | ★★★★ | ★★★※ | **3.40** | | atlas | 8 | ★★★★ | ★★★★ | ★★★ | ★★★ | ★★※ | **3.35** | | gstack | 150+ | ★★★★★ | ★★★★★ | ★★★★ | ★★ | ★★★★ | **4.20** | | defuddle | 1 | ★★ | ★★★ | ★★ | ★★★★★ | ★★★※ | **2.85** | | ffmpeg-skill | 未核验※ | ★★★½※ | ★★½※ | ★★★½※ | ★★★ | ★★★★½ | **3.33※** | 注意这张表的形状：综合分最高的 gstack 不是人人都该学的目标，上手分最高的 defuddle 也不是随便糊弄的反例——**它们各自答对了属于自己的那套决策题**。下面把这套题摆出来。 ## 三、四道门逐道讲 ### 门一：形态——这件事配得上一个「件」吗 第一个决定不是「怎么写」，而是「要不要写」。skill-factory（社区中文造件工厂，本栏目造件机拆解存档）在品味守则里有一条锋利的判词：把通用 AI 能力包装成 Skill，「那不是 Skill，只是提示词」。反过来也成立：不是所有重复劳动都需要一个件。 三个判据，命中任意一条才值得开目录： 1. **有多步固定流程**——收集素材、分类、排版、自查，步骤顺序有讲究，不是一句话能带过； 2. **有格式或验收纪律**——产出要对着一个标准校准（公文格式、公告骨架、代码规范）； 3. **需要捆绑资源**——脚本、模板、长文档，这些东西散在对话里每轮都要重新交代。 三条全不命中，你要的只是一个常用片段，存进笔记比装进 `~/.claude/skills/` 诚实。本周新架潮里的命令壳件（ffmpeg-skill 一类）是这个门的正面样本：转码参数组合是标准的多步流程加格式纪律，值得一个件；而「帮我写得更正式一点」这种活，写成件就是把提示词换了口锅。 ### 门二：通道——它该住在哪一层 形态定了「要写」，下一个决定是「写在哪」。生态里现成的通道至少四条，选错的件会终生别扭： - **CLAUDE.md / 记忆层**：每次会话都要生效的偏好与规矩（代码风格、提交规范），没有触发概念，常驻。把这种活写成触发型 Skill，等于给天天要用的东西装了一道门禁——每次都要喊对暗号才生效。 - **hook 层**：不劳模型判断、由事件强制执行的拦截与自动化。本周小而美榜的 lennney/stop-that-shit（⭐1934）是活教材：它拦的是 AI coding agent 无需求的哈希计算、校验和与任务范围膨胀——这类「无条件必须执行」的规矩走 hook，比写进任何正文都可靠，因为模型没有选择权。 - **Skill（触发型）**：有明确使用时机、多步流程、可捆绑资源的领域活。这是本栏目的主场。 - **MCP**：要对接口的外部系统（调试器、浏览器、数据库），别在 SKILL.md 里硬壳。本周小而美榜头名 duty1g/x64dbg-mcp-server（⭐1945）的选型值得抄：作者用 Zig 写 x64dbg 原生插件而非外挂 HTTP 壳，因为他们清楚调试器集成必须贴着进程走——该走 MCP 的活，通道本身就是工程决定。 一句话自检：**需要「每次都管」的去记忆层，需要「无条件执行」的去 hook，需要「外部世界」的去 MCP，剩下的才轮到 Skill。** ### 门三：分层——哪些活留在正文，哪些沉下去 形态与通道都落在 Skill 上，才轮到今天前两篇讲过的写作本身。但下笔前还剩一个结构性决定：一页纸里什么都有，还是分家。官方 skill-creator 给的三层装载是这套决定的底座（造件机拆解存档）：元数据常驻上下文约 100 词；正文触发时整页注入，理想 500 行以内；捆绑资源按需取用——**脚本能执行而不必载入**。装机目录的件型梯度就是这三层不同充实度的实录： | 件（文件数实测） | 分层结构 | 分层决定的对错点 | |---|---|---| | defuddle（1） | 仅 SKILL.md | 小活不分家，一张名片正好 | | openstoryline-use（3） | 正文 + 2 个 Python 脚本 | 干完活就交接（推飞书），脚本只做桥 | | long-running-agent（5） | 正文 + 2 参考提示词 + 2 资产模板 | 方法论做成可复制模板，正文保持薄 | | atlas（8） | 正文 + scripts + references + agents | 8 个文件开始出现跨宿主门 | | gstack（150+） | 六层完整建制 | 说明书写过两千字就必须按读者分家 | 下笔前的分层口诀四句：**确定性算术沉进 scripts/**（排序、统计、格式变换——模型手算一万次错一次，脚本跑一万次一个样）；**长文档与多领域参考外挂 references/**（skill-creator 的原例：cloud-deploy 拆 aws/gcp/azure 三份，模型只读相关那份）；**产出骨架放 assets/**（模板不占上下文，用时取）；**品味与取舍留在正文**（frontend-design 存档那篇的核心：审美方向、负面清单这类判断题，脚本和参考文件都替不了）。 分层还有一个 gstack 补充的高级条款：当件长大到多处重复同一信息（版本号、命令清单）时，学它用 `SKILL.md.tmpl` 模板生成门面——手工维护的最常见事故是「文档说有这个命令，实际早删了」，模板化从根上掐死失同步。 ### 门四：回收——出错和退场怎么办 最后一道门最少人走。下笔前要回答两个问题：**出错时模型该干什么，用户不用时怎么送走。** 出错出口的正反样本都在档：skill-creator 的评测铁律规定 grading.json 字段必须是 `text`、`passed`、`evidence`、「the viewer depends on these exact field names」——下游依赖的格式必须由纪律锁死；而装机目录里那台社区造件工厂 skill-factory，正文尾部署名处赫然留着 `https://github.com/your-repo/skill-factory` 占位符——造件的工厂自己的模板没过人眼。两个样本指向同一条下笔前就要写的规则：**失败路径要显式写**（脚本退出码非 0 时报错并停，不许模型改用自己猜的命令硬来），**交付前有一步人眼**。 退场设计看 gstack 的文件树：`gstack-update-check` 配 `gstack-uninstall`，`bin/dev-setup` 配 `bin/dev-teardown`——每个有副作用的动作都配了对称的回收动作。你的第一件未必需要卸载器，但下笔前至少想清楚：这个件会产生中间文件吗？会改用户的配置吗？答案如果出现一个「是」，回收动作就该在第一次提交里，而不是第二次事故后。 ## 四、四道门的决策图 ```mermaid flowchart TD A["一个重复需求到手"] --> B{"多步流程或
格式纪律吗"} B -->|都没有| R1["存成常用片段
别写件"] B -->|有| C{"每次会话
都要生效吗"} C -->|是| R2["写进记忆层
CLAUDE.md"] C -->|否| D{"要对接外部
系统或进程吗"} D -->|是| R3["改走 MCP 通道"] D -->|否| E{"活里有确定性
算术或重活吗"} E -->|有| R4["SKILL.md 加 scripts
外挂 references 与 assets"] E -->|无| R5["单文件名片件
一页写完"] ``` 十一个节点，五条出口。多数教程从 R4、R5 那两格才开始教，但真正拉开件与件差距的，是前四个格子。 ## 五、实战走门：把一个真实需求走完全程 需求样本取一个所有人都会撞上的：**每次发版，要把 git log 整理成一份中文更新公告**。四道门依次过： **过门一（形态）**：读 log、按功能分类、套格式排版、核对版本号——多步流程命中，格式纪律命中，值得写件。✅ **过门二（通道）**：不是每次会话都写公告（排除记忆层）；不需要强制拦截（排除 hook）；数据源是本机 git 仓库，命令行可直接访问，无需常驻外部进程（排除 MCP）。落点：触发型 Skill。✅ **过门三（分层）**：版本号排序、提交去重、区间统计是确定性算术，沉进 `scripts/`；分类措辞表和禁用词是长参考，外挂 `references/`；公告骨架是产出模板，放 `assets/`；「什么算一个功能、什么算修复」的分类判断留正文。✅ **过门四（回收）**：空区间、无标签、浅克隆缺历史——脚本必须给退出码，正文必须规定「报错即停，不编造」；本件无副作用，卸载即删目录，但要写明生成物落盘位置。✅ 落出来的目录树： ``` release-notes-zh/ ├── SKILL.md # 正文控制在 60 行内 ├── scripts/ │ └── collect.py # git log 解析、版本排序、贡献者去重 ├── references/ │ └── style.md # 分类措辞表、禁用词、示例对照 └── assets/ └── template.md # 公告骨架 ``` SKILL.md 里三句关键写法（写法原理详见今日前两篇存档，此处只放落位示范）： ```markdown name: release-notes-zh description: 把 git 提交记录整理成中文发版公告时使用。当用户提到「发版公告」 「更新日志」「release notes」「changelog」，或让你根据版本区间整理变更时都要用， 即使用户没有说出「公告」二字。 ## 取数（不要手工做） 版本区间、提交数量、贡献者去重一律运行 scripts/collect.py 获取—— 手工数会漏掉 merge 提交，数字对不上会在评审会上被戳穿。 ## 失败即停 collect.py 退出码非 0 时，把 stderr 原样转告用户并停止， 不要改用自己猜的 git 命令补救。 ``` 写完做三步验收（轻量版，从 skill-factory 的五句触发验证改造）：两句明确触发（「帮我写 0.3.0 的发版公告」）、两句模糊触发（「把这周提交整理一下发出去」）、一句边缘（「把这个月报改写成公告格式」）——门牌盖不住就回炉；再喂一次空区间输入，看它会不会老实报错。三步跑完，你的第一件就从「写完了」变成「验过了」。 ## 六、推荐排行榜 - **最该先抄的一个决定**：defuddle 的「1 文件也是正经件」——第一件从名片起步，先让它被触发、被用上 - **最该警惕的一个决定**：gstack 的 150+ 文件——作业值得抄，但先问自己的任务配不配这个重量 - **本周最贵的一课**：ffmpeg-skill——需求再硬，千星也补不回空着的触发面；先写 description，再谈功能 - **通道选型的活教材**：stop-that-shit 走 hook、x64dbg-mcp-server 走原生 MCP——都不是「写成 Skill 就完了」 - **下笔顺序建议**：先写门牌（触发面），再写失败出口（回收），最后写正文流程——重要性与写作顺序恰好相反 ## 七、安装与动手命令 ```bash # 第一道门之前：先搜生态里有没有现成的，有就用，别重复造 npx skills find release notes # 确实要自己造：四道门过完，目录一次建齐 mkdir -p .claude/skills/release-notes-zh/scripts mkdir -p .claude/skills/release-notes-zh/references mkdir -p .claude/skills/release-notes-zh/assets # 起草与调优时，把官方造件机拉进来当陪练 npx skills add anthropics/skills@skill-creator -g -y # 装完自检：确认门牌被识别 ls ~/.claude/skills/release-notes-zh/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 等场景全覆盖。