# 从拆到造：手写Skill全流程——收官轮，把七轮拆出的规律当场用一遍 ## 概述 本期是 Skills 生态拆解的第 8 轮，也是本系列的收官轮。前七轮拆了四十余个样本，验证了写法、拆了结构、对了赛道；但拆解证明的是「这个 Skill 为什么行」，证明不了「你也能写出行」——这两件事隔着一条动手的鸿沟。所以本期不再新拆对象（本周可拆的面孔已被第 1 至 7 轮开采完毕，模式层也被今日存档《本周爆款Skill的八种写法》收敛成四层框架），而是把方向倒过来：**当面从空目录开始，写一个完整可用的 Skill，每一处写法都注明抄自哪个已被验证的样本**。案例选的是生态里尚无同名在册件的 `changelog-writer`——从 git 历史编译面向用户的更新日志。核心发现一句话：写 Skill 的难点不在正文在路由，description 是唯一的大门，正文只是触发之后才被读的说明书。 ## 一、为什么收官轮反过来「造」 ## 二、第一步：选题与命名——名字即合约 选题三条标准：真实痛点、小到一篇教程能装下、生态里没有同名在册件。`changelog-writer`（从 git 提交历史生成面向用户的更新日志）三条全中：每个发过版的人都手写过 release notes；范围只有一个输入（提交历史）一个输出（markdown 分节）；本会话注册表与本站七轮存档均无同名件。 命名抄 06-0607 存档提炼的 P3——**动词锁定职责**。gh-fix-ci 不叫 gh-ci、不叫 ci-agent，`fix` 一个动词把职权范围钉死。同理 `changelog-writer` 的 `writer` 把它和 `changelog-linter`、`changelog-checker` 划清界限：它写，不审。名字是用户预期与触发匹配的第一道合约，合约越窄，违约（触发错场景）越少。 ## 三、第二步：description 逐字段——唯一的大门 这是全文最重要的一节。Agent 在路由时**只看 frontmatter 的 description，不看正文**——正文是触发之后才加载的。这意味着描述里少写一个触发场景，等于那个场景永远走不进来。先看本会话注册表里四个已被验证的真实范本： - `claude-api`：「TRIGGER when: code imports 'anthropic'… SKIP: file imports 'openai'…」——正负双向路由的教科书，触发条件和排除条件写在同一段里； - `update-config`：「Automated behaviors … require hooks configured in settings.json. … memory/preferences cannot fulfill them」——主动说明「别的机制为什么做不到」，堵住错误路由（06-0607 存档的 P1 反模式排除）； - `fewer-permission-prompts`：「Scan your transcripts … then add a prioritized allowlist to project .claude/settings.json」——输入、动作、落点，一句话三要素； - `loop`：「Run a prompt or slash command on a recurring interval (e.g. /loop 5m /foo, defaults to 10m)」——描述里直接带用法示例，降低用户的心智成本。 照这四个范本，`changelog-writer` 的描述这样写，四个短句各扛一职： ```yaml name: changelog-writer description: Compile user-facing release notes from the repo's git history. Use when the user asks for a changelog, release notes, "what's new", or a version bump summary. Entries come from scripts/collect.sh output — never invent entries absent from commit history. Do not use for internal API docs or commit-lint tasks. ``` - 第一句**能做什么**：动词开头（Compile），宾语带范围限定（user-facing、from git history）——「面向用户」四个字排除了「给我列一下这周提交」这类内部诉求； - 第二句**何时触发**：Use when 后面跟的不是功能清单，而是**用户会打出的原话**——changelog、release notes、"what's new"、version bump。路由匹配的是字符串，不是意图，所以描述里要预埋用户的话术； - 第三句**事实来源声明**：never invent entries absent from commit history——把反幻觉从道德要求降维成机制设计，与第四节的脚本配合才成立； - 第四句**负向排除**：Do not use for internal API docs or commit-lint tasks——抄 claude-api 的 SKIP 结构。描述是单向大门，写清「不伺候谁」不会赶走用户，只会救回被误触发的上下文。 ## 四、第三步：正文——触发之后才被读的说明书 正文结构与描述层分工明确：描述管「来不来」，正文管「来了灵不灵」。全文骨架四段，正文控制在几十行内——七轮拆解里没有一个高分样本的正文超过几百行，规则越具体越可判，篇幅越长越像许愿清单（0343 存档对书改类「目录翻译」的批评）。 ```markdown # Changelog Writer Compile release notes from git history. Facts come from commits, not memory. ## Workflow 1. Run scripts/collect.sh — it outputs commits grouped by Added / Changed / Fixed / Breaking. 2. Rewrite each bullet for end users: drop internal jargon, keep behavior changes. 3. If collect.sh returns nothing, say so. Do not fabricate entries. 4. Show the draft to the user before appending to CHANGELOG.md. ## Boundaries - Breaking changes must quote the original commit hash. - Never edit past entries in CHANGELOG.md — append only. ## Output One H2 per version, one bullet per user-visible change. ``` 逐段对应的设计依据：第一行重述事实来源（正文层的「书改」原则，抄 refactoring-ui-skill 那一路——规则必须具体到可判真假）；Workflow 第 1 步把取数外包给脚本（下一节展开）；第 3 步把「空结果」写成显式指令——反幻觉要求的正文化身，模型对空结果的脑补是更新日志造假的重灾区；Boundaries 的 append only 抄 fewer-permission-prompts 的最小爆炸半径（它只写项目级 settings.json，本件只追加不重写历史）；第 4 步「先给草稿再落盘」把人留在回路上，这是七轮样本里治理层的共识写法。 ## 五、第四步：工程化——把事实外包给脚本 09-03 第 3 轮存档给「以运行时事实为准绳」家族做过定位：webapp-testing 以渲染后 DOM 为准、x64dbg 以断点内存为准、reverify 以二进制本体为准。`changelog-writer` 加入这个家族的方式是：**以 git 历史为准**。模型对「这个版本改了什么」的任何回忆都不可信，可信的只有 `git log` 的输出。 ```bash #!/usr/bin/env bash # scripts/collect.sh FROM="${1:?usage: collect.sh }" TO="${2:-HEAD}" git log --no-merges "$FROM..$TO" --pretty='%s|%h' | awk -F'|' ' /^feat/ {print "Added|" $0; next} /^fix/ {print "Fixed|" $0; next} /^perf/ {print "Changed|" $0; next} /BREAKING/ {print "Breaking|" $0; next} {print "Other|" $0}' ``` 十几行 bash，换来三件事：分类确定性（conventional commits 前缀机械映射，不劳模型猜）、防幻觉地基（描述与正文的 never invent 都指着这个脚本的输出兑现）、可独立测试（脚本错了改脚本，不用动提示词）。这是 0343 存档工程层的全部要义：scroll-craft 用 shoot 脚本逐滚动位截图自证页面不塌，本件用 collect.sh 自证条目有出处——技能自己产出证据，而不是请求信任。 ## 六、第五步：验证与发布——从空目录到被收录 ```bash mkdir -p ~/.claude/skills/changelog-writer/scripts # 写入 SKILL.md（第三、四节全文）与 scripts/collect.sh（第五节） npx skills find changelog # 确认无重名、发布后确认可被检索 git init && git add . && git commit -m "changelog-writer v0.1" # 推送到公开仓库，README 附一行安装命令： # git clone https://github.com//changelog-writer ~/.claude/skills/changelog-writer ``` ## 七、用本系列的尺子量自己 七轮评测用的五维权重表，收官轮反过来当作者的自检清单——写完描述量一次，写完正文量一次，缺哪维补哪维： | 维度 | 权重 | changelog-writer 草稿自评 | 依据 | |---|---|---|---| | 功能完整度 | 25% | ★★★☆ | 单一职责闭环；monorepo、非 conventional commits 仓库未处理 | | 设计质量 | 25% | ★★★★ | 双向路由、事实外包、append-only，四层各占一项 | | 实战效果 | 20% | 待实测 | 本文未跑分，空缺 | | 上手难度 | 15% | ★★★★★ | 零依赖，一个 bash 脚本 | | 社区活跃度 | 15% | — | 新草稿无数据，空缺 | 两维空缺，按本系列的规矩**不给加权总分**——一个只有草稿的技能不配拥有分数，这是本文对自己执行的反幻觉纪律。 ## 八、一个 Skill 的生命周期 收官轮的机制图不是某件的工作流，而是所有件共用的路由链路——看懂这张图，就看懂了为什么 description 值得逐字打磨： ```mermaid flowchart TD A[用户发来一条消息] --> B{匹配 description} B -- 未命中 --> C[这个 Skill 等于不存在] B -- 命中 --> D[加载 SKILL.md 正文] D --> E[按正文流程执行] E --> F{有确定性脚本?} F -- 有 --> G[运行脚本拿到事实] F -- 没有 --> H[模型凭参数推理] G --> I[按约定格式交付] H --> I I --> J{产出可验证?} J -- 可验证 --> K[信任累积 装机增长] J -- 不可验证 --> L[用一次即弃] ``` C 节点是生态里大多数沉默技能的坟场：不是写得差，是根本没被触发。K 与 L 的分岔则是本周增长数据的分水岭——goldie 与 backpass（616→624→697 三期）都活在 K 侧。 ## 九、收官排行榜：最值得抄的范本 - **按描述工程**：claude-api（TRIGGER/SKIP 双向，注册表一手）＞ sepia（08-31 期「设计质量第一」评语，三期 1307→1557）＞ update-config（反模式排除） - **按工程结构**：scroll-craft（shoot 脚本自证，09-01→09-03 1355→1593）＞ refactoring-ui-skill（书改可判规则，459→471→502）＞ changelog-writer 草稿（collect.sh，待实测） - **按治理边界**：fewer-permission-prompts（只收 read-only）＞ update-config（锁定项目级）＞ changelog-writer（append-only） - **按周内加权分**（引 0343 存档口径，各轮权重不一仅供参考）：video-talkcraft 3.80 ＝ headcount 3.80 ＞ refactoring-ui-skill 3.78 ＞ reverify 3.35 ＞ open-seo-mcp-skills 3.25 ## 安装与使用 本文主角 `changelog-writer` 的完整安装见第六节命令块。范本仓库按需取用： ```bash git clone https://github.com/Nanako0129/sepia ~/.claude/skills/sepia git clone https://github.com/nateherkai/scroll-craft ~/.claude/skills/scroll-craft git clone https://github.com/s0xDk/refactoring-ui-skill ~/.claude/skills/refactoring-ui ``` 八轮下来，生态的分工已经清楚：市场在奖励「描述写得准、产出可验证」的件，星数只是这个奖励的滞后读数。下一轮起本栏目转入新周期，读者若按本文流程造出了自己的第一个 Skill，欢迎带着星数曲线回来对账。 ## 参考来源 > [!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 等场景全覆盖。