从零打造变更日志生成技能

本教程将带你从零创建一个完整的 Claude Code 自定义 Skill——changelog，它能扫描两次发布之间的 Git 历史，按 Keep a Changelog 规范自动生成或更新 CHANGELOG.md。通过这个真实、可运行的案例，你将掌握 Skill 的目录结构、frontmatter 配置、动态上下文注入、辅助文件分层、调用控制与迭代评测的完整方法论，学完即可迁移到任意自定义工作流。

一、适用人群与前置条件

适用人群：已经能在 Claude Code 里跑通基本对话与 / 命令、想把自己重复粘贴的"操作清单"固化成可复用能力的开发者。

前置条件：

• Claude Code v2.1.145 或更高版本（claude --version 可查，部分特性如 /run 系列要求此版本以上）。
• 一个本地 Git 仓库（带至少一个 tag 更佳，没有也能跑）。
• 了解 Markdown 基本语法，能看懂 YAML 前置元数据。
• 终端能执行 git、mkdir、cat 等基础命令。

无需任何编程框架——Skill 本质上是"一个文件夹 + 一个 SKILL.md"，这点是它最容易上手的特性。

二、先搞清楚：Skill 到底是什么

在 Claude Code 的体系里，一个 Skill 就是一个文件夹，文件夹里至少有一个 SKILL.md 作为入口。SKILL.md 由两部分组成：

1. YAML frontmatter（夹在两个 --- 之间）：告诉 Claude 这个 Skill 做什么、什么时候该用它。
2. Markdown 正文：Claude 在 Skill 被激活后遵循的具体指令。

关键的一点是渐进式披露（Progressive Disclosure）：Claude Code 在会话启动时只会把每个 Skill 的 description 字段加载进上下文（成本极低），而正文只有在 Claude 判断"这次任务跟它相关"时才会按需加载。这意味着你可以放心地堆砌大量参考文档——只要把它们放在辅助文件里，正文保持精简，平时就几乎不占 token。

另一个要记住的认知：自定义命令已经并入 Skill 体系。过去放在 .claude/commands/deploy.md 的文件，和放在 .claude/skills/deploy/SKILL.md 的 Skill，都会生成 /deploy 命令并等价工作。Skill 是更新的、功能更全的形态（支持辅助文件、frontmatter 控制调用方式、按需自动加载）。

三、分步实战：搭建 changelog Skill

第 1 步：决定 Skill 的"存放层级"

Skill 的存放位置决定了谁能用、用在哪：

同名冲突时的优先级是 企业级 > 个人级 > 项目级；插件 Skill 用 插件名:技能名 命名空间，不会和别的层级冲突。此外，项目级还能"穿透"父目录——从子目录启动会话时，仓库根目录的 .claude/skills/ 也会被发现；monorepo 的子包 apps/web/.claude/skills/deploy/ 则会以带目录前缀的名字 apps/web:deploy 出现。

我们的 changelog 是个跨项目通用的能力，放在个人级最合适：

mkdir -p ~/.claude/skills/changelog

预期结果：目录创建成功，无输出。后续所有文件都放在 ~/.claude/skills/changelog/ 下。

第 2 步：写入口文件 SKILL.md

把下面内容存为 ~/.claude/skills/changelog/SKILL.md：

---
description: Generates or updates CHANGELOG.md from git history between two refs. Use when the user wants to draft release notes, prepare a version bump, or summarize what changed since the last tag.
---

## Git history since the last tag

!`LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null); if [ -n "$LAST_TAG" ]; then echo "Ref range: $LAST_TAG..HEAD"; git log $LAST_TAG..HEAD --pretty=format:"- %s"; else echo "No previous tag found; showing last 30 commits"; git log -30 --pretty=format:"- %s"; fi`

## Instructions

You are generating release notes following the "Keep a Changelog" convention.

1. Read the commit list above.
2. Categorize each commit into Added / Changed / Fixed / Removed / Security using the rules in `references/category-rules.md`.
3. Merge duplicate or related commits into a single bullet.
4. Output the new version section using the format in `template.md`.
5. If `CHANGELOG.md` exists in the repo root, insert the new section near the top (below the header) using the Edit tool; otherwise create it from `template.md`.
6. Commits you cannot confidently classify go under "Changed" with a short note flagging the uncertainty.

Do NOT invent commits that are not in the list. Do NOT include merge commits. Keep bullets in the imperative-mood style of the source commits.

这里有几个关键设计，逐个拆解：

• 只写 description，没写 name：官方模板里 name 是必填，但 Claude Code 实际允许省略——目录名 changelog 会自动成为命令名 /changelog。不过为保险起见，你也可以补上 name: changelog。
• description 是"红娘"：它永远在上下文里，是 Claude 判断"要不要自动触发这个 Skill"的唯一依据。务必写清楚做什么 + 什么时候用，并埋入用户会说的自然语言（"release notes""version bump""what changed"）。不要把实现细节塞进来。
• !\命令`` 是动态上下文注入：这一行在 Claude 看到正文之前就被执行，输出原地替换掉这一行。于是指令到达时，当前仓库的真实 commit 列表已经内联好了——这正是 Skill 能"读懂实时数据"的根基。
• 正文精简、引用辅助文件：references/category-rules.md 和 template.md 都是按需加载的，平时不进上下文。这就是渐进式披露的落地。

预期结果：保存后无需重启——Claude Code 会监视 Skill 目录，SKILL.md 的改动在当前会话内即时生效（即"实时变更检测"）。

常见问题：把 Skill 嵌套深了一层是最常见的错误。正确路径是 ~/.claude/skills/changelog/SKILL.md，不是 ~/.claude/skills/changelog/某文件夹/SKILL.md。可用 ls ~/.claude/skills/changelog/ 验证，应直接看到 SKILL.md。

第 3 步：添加辅助文件（分层加载）

创建目录与文件：

mkdir -p ~/.claude/skills/changelog/references
mkdir -p ~/.claude/skills/changelog/examples

references/category-rules.md（分类规则，详尽但平时不加载）：

# Commit → Category Mapping

- **Added**: feat, add, new, create, introduce, support
- **Changed**: refactor, update, change, improve, migrate, bump (deps), rework
- **Fixed**: fix, bug, resolve, patch, correct, repair, handle (edge case)
- **Removed**: remove, delete, drop, strip (only when actually removed)
- **Security**: security, CVE, vulnerability, auth, leak, sanitize, escape

Conventional Commits prefixes (`feat:`, `fix:`, `chore:`, `docs:`) take priority
over keyword matching. A `chore:` that bumps deps counts as "Changed".

Uncertain commits → default to **Changed** and flag for review.

template.md（输出模板）：

# Changelog

All notable changes to this project are documented here.
The format is based on [Keep a Changelog](https://keepachangelog.com/).

## [UNRELEASED]

### Added
-

### Changed
-

### Fixed
-

examples/sample-output.md（示例输出，让模型对齐格式）：

## [1.2.0] - 2026-06-22

### Added
- Support for webhook signature verification

### Fixed
- Race condition in token refresh on slow networks

设计意图：把"规则"和"模板"从 SKILL.md 剥离出去。SKILL.md 一旦加载就跨轮常驻上下文，每多一行都是持续 token 成本；而分类规则、示例这种"查完就走"的资料放进辅助文件，只有 Claude 真正需要时才读一次。这是控制 Skill 长期成本的核心技巧。

第 4 步：控制"谁来触发"——调用控制

changelog 这种 Skill，你通常想主动调用（敲 /changelog），而不是让 Claude 在你聊到一半时擅自触发。官方 frontmatter 提供两个开关：

• disable-model-invocation: true：禁止 Claude 自动触发，只能手动 /changelog 调用。
• context: fork：让 Skill 在子代理（subagent）里执行，主对话上下文不被污染，适合会产生大量中间输出的任务。

给我们的 Skill 加上手动调用倾向。修改 frontmatter：

---
name: changelog
description: Generates or updates CHANGELOG.md from git history between two refs. Use when the user wants to draft release notes, prepare a version bump, or summarize what changed since the last tag.
disable-model-invocation: true
---

说明：对 changelog 这种"生成一段相对长的文档"的任务，context: fork 也很值得加——它在独立子代理里跑，跑完只把结果摘要交回主线，避免几十条 commit 的解析过程刷屏。但加了 fork 后子代理看不到主会话历史，需要的话要把必要上下文写进正文或用动态注入喂给它。本例所有数据都来自 git log，所以加 context: fork 是安全的。

反过来看，参考类 Skill（比如"本仓库 API 设计规范"）就不要加 disable-model-invocation——你要的就是让 Claude 在写代码时自动想起它。

第 5 步：实测两种触发方式

进入任意一个有提交历史的 Git 仓库，启动 claude。

方式 A：手动直接调用

/changelog

方式 B：让 Claude 自动识别（前提：你没设 disable-model-invocation: true，或临时想验证 description 写得好不好）

帮我把自上个版本以来的改动整理成发布说明

预期结果：Claude 先读取 SKILL.md、执行其中的 git log 注入拿到 commit 列表，按需读取分类规则和模板，然后把结果写入或更新仓库根目录的 CHANGELOG.md，最后给你一段新增内容的摘要。

常见问题： - Skill 没触发：八成是 description 写得太泛或没包含用户会说的词。重写描述，加入具体场景短语；用 /help 或会话内观察 Claude 是否"读到"了这个 Skill。 - description 被截断：description 上限 1024 字符，过长的会被截断导致后半部分触发词丢失。精简到关键场景即可。 - 改了文件没生效：仅当你新建了一个会话启动时不存在的顶层 skills 目录时才需要重启；编辑已有 SKILL.md 无需重启。

第 6 步：用 Evals 闭环打磨

Skill 写完不算完，要靠评测来保证"换个仓库、换批 commit 还能稳定产出"。Claude Code 的 skill-creator 内置了评测能力。核心思路是准备几组"输入→期望输出"的样例，跑 Skill、对比结果、迭代 description 与规则。

一个最小评测集可以这样组织（放仓库或临时目录）：

evals/
├── case-1-feat-fix.txt      # 输入：模拟的 commit 列表
├── case-1-expected.md       # 期望：分类后的输出
├── case-2-mixed.txt
└── case-2-expected.md

评测关注三件事：

1. 触发准确性：描述相似但不同义的请求（比如"帮我写提交信息" vs "帮我整理发布说明"）会不会被错误触发或漏触发。
2. 分类正确率：fix: 是否稳定落到 Fixed，chore(deps): bump 是否落到 Changed。
3. 格式一致性：是否始终遵循 template.md，日期、版本号占位是否被正确替换。

每轮迭代只改一个变量（改 description、或改分类规则、或改正文指令），再跑评测——这是把 Skill 从"能用"推向"可靠"的唯一路径。

四、实战案例：完整可运行的 changelog Skill

把前面所有片段拼起来，最终目录长这样：

~/.claude/skills/changelog/
├── SKILL.md                    # 入口：description + 动态注入 + 精简指令
├── template.md                 # CHANGELOG 骨架模板
├── references/
│   └── category-rules.md       # commit→分类映射（按需加载）
└── examples/
    └── sample-output.md        # 期望输出样例（按需加载）

在真实仓库里走一遍：

# 1. 进项目
cd ~/projects/my-api
git tag v1.1.0   # 假设上个发布点

# 2. 期间有若干提交
git commit -m "feat: add webhook signature verification"
git commit -m "fix: token refresh race on slow networks"
git commit -m "chore(deps): bump express to 4.19"

# 3. 生成发布说明
claude
> /changelog

Claude 会执行动态注入拿到三条 commit，按 Conventional Commits 前缀分类，输出并写入 CHANGELOG.md：

## [1.2.0] - 2026-06-22

### Added
- Support for webhook signature verification

### Fixed
- Race condition in token refresh on slow networks

### Changed
- Bump express to 4.19

如果仓库里已有 CHANGELOG.md，Skill 会把这段插到顶部 ## [Unreleased] 之下；没有则按 template.md 新建。整个过程不需要你复制粘贴任何 commit 信息。

五、工作流程全景图

flowchart TD
    A[会话启动] --> B[加载所有 Skill 的 description 进上下文]
    B --> C{用户请求 / 自动判断}
    C -->|匹配 description| D[加载该 Skill 的 SKILL.md 正文]
    C -->|/skill-name 手动调用| D
    D --> E[执行动态注入 !\`命令\`]
    E --> F{正文是否引用辅助文件?}
    F -->|是| G[按需读取 references/ template/ examples/]
    F -->|否| H[仅用正文+注入数据]
    G --> H
    H --> I[执行指令 生成/编辑结果]
    I --> J{context: fork?}
    J -->|是| K[在子代理执行 摘要回主线]
    J -->|否| L[在主上下文执行]
    K --> M[输出 CHANGELOG 更新]
    L --> M

这张图串起了本教程所有概念：description 常驻、正文按需、动态注入先于正文执行、辅助文件分层、调用控制决定执行位置。

六、本教程的方法论提炼

虽然案例是"变更日志生成"，但你要带走的是这套通用四步法，套到任何自定义 Skill 上都成立：

1. 先定层级与触发意图：放个人还是项目？让 Claude 自动触发还是手动 / 调用？想清楚再动 disable-model-invocation 和 context: fork。
2. description 当"广告位"：永远在线，决定被发现概率。写"做什么 + 何时用 + 用户原话"，拒绝实现细节。
3. 正文精简 + 动态注入：能从环境实时拿的数据（git、文件、命令输出）一律用 !\命令`` 注入，别让模型靠猜。正文只留决策与编排逻辑。
4. 重资料下沉到辅助文件：规则、模板、示例进 references/、examples/，按需加载。这控制的是 Skill 的长期 token 成本。

七、延伸阅读

• 官方 Skill 文档：code.claude.com/docs/en/skills —— frontmatter 字段、调用控制、动态注入的权威来源。
• Anthropic Skills 开放仓库：github.com/anthropics/skills —— 含 template/ 起步模板和大量真实 Skill 范例（docx/pdf/pptx 等生产级实现）。
• Agent Skills 开放标准：agentskills.io —— Skill 跨工具（Claude Code / OpenClaw / Codex CLI / Cursor）互通的规范基础。
• skill-creator 内置技能：直接在 Claude Code 里跑 /skill-creator，可以脚手架新 Skill、优化 description、跑评测并做方差分析。

八、训练营适用性评估

本教程刻意把案例选在"文档生成"这一与前序代码扫描类 Skill 不同的品类，目的是让学员理解：Skill 的威力不在某个垂直场景，而在"指令 + 动态数据 + 分层文件 + 调用控制"这套可迁移的骨架。掌握了它，下一个 Skill 你该造什么，答案就在你自己每天重复粘贴的那段操作清单里。

参考来源

1. Extend Claude with skills — Claude Code Docs — 官方 Skill 完整文档，含 frontmatter 参考、动态注入、调用控制、层级优先级等权威说明。
2. anthropics/skills — GitHub — Anthropic 官方 Skill 仓库，提供 template/ 起步模板及 docx/pdf/pptx 等生产级 Skill 实现参考。
3. Where Are Claude Skills Stored? Paths for Mac, Windows, Linux — Agensi — 个人级/项目级 Skill 存放路径与常见嵌套错误排查指南。
4. Progressive Disclosure in AI Agent Skill Design — Towards AI — 把 UX 的渐进式披露原则应用到 SKILL.md 结构设计的实践方法。
5. Core Concepts and Progressive Disclosure — anthropics/claude-cookbooks (DeepWiki) — 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 等场景全覆盖。