构建你的第一个 Agent Skill：实操 walkthrough

你已经装过几个 Skill 且能正常工作，现在想为自己的工作流做一个：团队特有的代码评审流程、统一的 API 响应格式，或手工执行的发布清单。

本教程从零做一个真实 Skill。

要构建什么

一个「release-notes」Skill：根据 git 提交历史生成结构化发布说明。多数团队需要，但很少有人爱手写。

完成后 Skill 将：

1. 读取近期 git log
2. 按类型分类（feat、fix、refactor 等）
3. 生成 Markdown 发布说明
4. 遵循团队格式约定

步骤 1：创建 Skill 目录

Claude Code 下 Skill 在本地技能目录：

mkdir -p ~/.claude/skills/release-notes
cd ~/.claude/skills/release-notes

步骤 2：编写 SKILL.md

创建 SKILL.md：

---
name: release-notes
description: Generate structured release notes from git commit history, categorized by change type
---

正文用 Markdown 写指令：

## Purpose

Generate release notes for the current repository based on recent git commits.

## When to activate

The user asks for release notes, changelog, or "what changed" for a version or time range.

## Instructions

1. Run `git log --oneline` to get recent commits. Default range: last 50 commits or since the last tag, whichever is smaller.

2. Categorize each commit by its prefix:
   - `feat:` or `feature:` → New Features
   - `fix:` or `bugfix:` → Bug Fixes
   - `refactor:` → Refactoring
   - `docs:` → Documentation
   - `test:` → Tests
   - `chore:` → Maintenance
   - No prefix → Other Changes

3. Group commits under these headings. Omit empty sections.

4. For each commit, include:
   - The commit message (without the prefix)
   - The commit hash (first 7 characters)
   - Do NOT include author names or dates unless specifically requested

5. Output format:

# Release Notes

## New Features
- Description of change (`abc1234`)
- Description of change (`def5678`)

## Bug Fixes
- Description of fix (`ghi9012`)

## Other Changes
- Description (`jkl3456`)

6. If the user specifies a version number, include it in the heading:
   `# Release Notes v1.2.0`

7. If the user asks for "full" release notes, include the commit body text below each entry.

## Important rules

- Do not fabricate commits. Only include what exists in git log.
- If the repo uses conventional commits, respect the format. If not, put everything under "Other Changes."
- Keep descriptions concise. Do not expand or interpret commit messages.

保存即可，这就是完整 Skill。

步骤 3：测试 Skill

在 git 仓库中打开 Claude Code：

cd ~/my-project
claude

询问：

Generate release notes for the last 2 weeks

Claude 应激活 Skill、跑 git log、分类并输出结构化结果。

若不对，改 SKILL.md。常见问题：前缀分类过严或过松，按团队约定调整前缀列表。

步骤 4：添加脚本（可选）

若需自动生成文件，可加 scripts/generate.sh：

#!/bin/bash
# Usage: generate.sh [since-tag] [version]
SINCE=${1:-$(git describe --tags --abbrev=0 2>/dev/null || echo "HEAD~50")}
VERSION=${2:-"$(date +%Y-%m-%d)"}

echo "# Release Notes $VERSION"
echo ""
git log "$SINCE"..HEAD --pretty=format:"- %s (%h)" | \
  sed 's/^- feat(\(.*\)):/- **\1**:/' | \
  sed 's/^- fix(\(.*\)): /- [\1] /'

在 SKILL.md 中引用：

## Scripts

- `scripts/generate.sh [since-tag] [version]` — generates a raw release notes file.
  Use this as a starting point, then refine with the full categorization instructions above.

步骤 5：发布到 GitHub

gh repo create my-org/release-notes-skill --public

cd ~/.claude/skills/release-notes
git init && git add . && git commit -m "feat: initial release-notes skill"
git remote add origin git@github.com:my-org/release-notes-skill.git
git push -u origin main

他人安装：

claude skill add --from-github my-org/release-notes-skill

好 Skill 的模式

1. 单一明确目的 — 只生成发布说明，不要顺带 changelog、部署说明。
2. 明确的激活条件 — Agent 需知道何时用本 Skill 而非其他。
3. 具体输出格式 — 示例比抽象描述更有效。
4. 诚实约束 — 「不要编造提交」防幻觉。
5. 脚本可选 — SKILL.md 是核心，脚本是加分项。

常见错误

• 目的太多 — 一个 Skill 一件事；出现「并且还要…」就拆成两个。
• 指令模糊 — 「生成好看的发布说明」不可执行；「按前缀分组、用下列 Markdown 格式」才可执行。
• 缺少 When to activate — 没有它，Agent 要么不用，要么用错时机。

想探索更多 Skill？见 SkillMap 排行榜。