Claude Code Skills开发实战全攻略：从零创建自定义Skill

CLAUDE.md ─── 全局加载，始终生效，定义通用规则和项目上下文
Skills/   ─── 按需加载，触发式激活，定义特定任务工作流

graph TB
    subgraph "Skill 三层加载系统"
        L1["第一层：Frontmatter<br/>元数据（名称、描述、触发条件）"]
        L2["第二层：SKILL.md 正文<br/>工作流指令"]
        L3["第三层：辅助资源<br/>scripts/ references/ assets/"]
    end
    L1 -->|"系统匹配时加载"| L2
    L2 -->|"需要时按需加载"| L3
    style L1 fill:#4A90D9,color:#fff
    style L2 fill:#7B68EE,color:#fff
    style L3 fill:#9370DB,color:#fff

graph LR
    subgraph "优先级从高到低"
        E["企业级<br/>管理员统一管理"]
        P["个人级<br/>~/.claude/skills/"]
        R["项目级<br/>.claude/skills/"]
        G["插件级<br/>plugin/skills/"]
    end
    E --> P --> R --> G
    style E fill:#E74C3C,color:#fff
    style P fill:#F39C12,color:#fff
    style R fill:#2ECC71,color:#fff
    style G fill:#3498DB,color:#fff

# 进入你的项目目录
cd your-project

# 创建 Skill 目录
mkdir -p .claude/skills/changelog-gen/scripts
mkdir -p .claude/skills/changelog-gen/references

.claude/skills/changelog-gen/
├── SKILL.md              # 核心指令文件（必需）
├── scripts/
│   └── git-log-fmt.sh    # Git 日志格式化脚本（可选）
└── references/
    └── template.md       # 输出模板参考（可选）

---
name: changelog-gen
description: >
  分析 Git 提交历史并生成结构化 CHANGELOG。
  当用户说"生成更新日志"、"changelog"、"版本变更记录"时触发。
  支持按版本号、日期范围、作者过滤提交。
trigger:
  - "生成更新日志"
  - "changelog"
  - "变更记录"
  - "版本更新"
  - "release notes"
allowed-tools:
  - Read
  - Write
  - Bash(git log *)
  - Bash(git tag *)
  - Bash(git diff *)
  - Glob
  - Grep
version: 1.0.0
author: your-name
tags: [git, changelog, release, documentation]
---

# 代码变更日志生成器

## 工作流程

### 第一步：收集提交信息

1. 运行 `git log --oneline --no-merges` 获取提交概览
2. 运行 `git tag --sort=-v:refname` 获取最近的版本标签
3. 确定变更范围：
   - 如果用户指定了版本号，使用 `git log v{prev}..v{curr}`
   - 如果用户指定了日期，使用 `git log --since="{date}"`
   - 默认使用自上一个 tag 以来的所有提交

### 第二步：分类整理

将提交按以下类别自动分组：
- 🚀 **新功能** (feat): 包含 "feat"、"add"、"新增"、"支持" 的提交
- 🐛 **Bug 修复** (fix): 包含 "fix"、"bug"、"修复"、"解决" 的提交
- ♻️ **重构** (refactor): 包含 "refactor"、"重构"、"优化" 的提交
- 📝 **文档** (docs): 包含 "docs"、"文档"、"README" 的提交
- 🔧 **配置** (chore): 包含 "chore"、"config"、"配置" 的提交
- ✅ **测试** (test): 包含 "test"、"测试" 的提交

### 第三步：生成 CHANGELOG

输出格式严格遵循以下模板：

```markdown
# Changelog

## [版本号] - YYYY-MM-DD

### 🚀 新功能
- **scope**: 简短描述 (#PR号)

### 🐛 Bug 修复
- **scope**: 简短描述 (#PR号)

### 其他变更
- 描述

### 2.3 创建辅助脚本（可选但推荐）

创建 `.claude/skills/changelog-gen/scripts/git-log-fmt.sh`：

```bash
#!/usr/bin/env bash
# 格式化 Git 日志为 JSON，方便 Claude 解析

set -euo pipefail

SINCE="${1:-}"
FORMAT='{ "hash": "%h", "subject": "%s", "author": "%an", "date": "%ad" }'

if [ -n "$SINCE" ]; then
    git log --since="$SINCE" --no-merges --format="$FORMAT" --date=short
else
    git log -50 --no-merges --format="$FORMAT" --date=short
fi

chmod +x .claude/skills/changelog-gen/scripts/git-log-fmt.sh

# 变更日志模板参考

## 标准格式
- 版本号遵循语义化版本 (SemVer)
- 日期格式：YYYY-MM-DD
- 每个变更条目以动词开头
- PR 号码放在括号内

## 示例输出
## [2.3.0] - 2026-06-09

### 🚀 新功能
- **api**: 新增批量导出接口 (#142)
- **ui**: 支持暗色模式切换 (#138)

### 🐛 Bug 修复
- **auth**: 修复 Token 过期后未自动刷新的问题 (#145)

/changelog-gen

帮我生成这个项目的更新日志

分析最近的 Git 提交，写一份 changelog

{
  "skill_name": "changelog-gen",
  "evals": [
    {
      "id": 1,
      "prompt": "生成这个项目的更新日志",
      "expected_output": "生成了包含版本号、日期和分类变更条目的 CHANGELOG.md 文件",
      "assertions": [
        {"name": "file-created", "text": "CHANGELOG.md 文件被创建或更新"},
        {"name": "has-categories", "text": "输出包含至少一个分类标题（新功能/Bug修复等）"},
        {"name": "has-date", "text": "包含日期信息，格式为 YYYY-MM-DD"}
      ]
    },
    {
      "id": 2,
      "prompt": "从 v2.0.0 到现在的变更记录",
      "expected_output": "仅包含 v2.0.0 之后提交的变更日志",
      "assertions": [
        {"name": "version-range", "text": "正确使用版本范围过滤提交"},
        {"name": "no-old-commits", "text": "不包含 v2.0.0 之前的提交"}
      ]
    },
    {
      "id": 3,
      "prompt": "最近一周的 changelog",
      "expected_output": "按日期范围过滤并生成变更日志",
      "assertions": [
        {"name": "date-filter", "text": "使用 --since 参数过滤日期"},
        {"name": "recent-only", "text": "只包含最近7天的提交"}
      ]
    }
  ]
}

/skill-creator eval changelog-gen

---
# ===== 必需字段 =====
name: my-skill                    # 唯一标识符，kebab-case 格式
description: >                    # 功能描述 + 触发场景（最关键的字段）
  一句话说明做什么。另一句说明何时触发。

# ===== 触发控制 =====
trigger:                          # 显式触发关键词（补充 description）
  - "关键词1"
  - "关键词2"
disable-model-invocation: false   # true = 只允许 /命令 手动触发
user-invocable: true              # false = 从 / 菜单中隐藏

# ===== 执行环境 =====
context: default                  # default 或 fork（隔离子代理）
model: sonnet                     # 覆盖模型：sonnet/opus/haiku
effort: high                      # 努力级别：low/medium/high/max
agent: Explore                    # context:fork 时的子代理类型

# ===== 权限控制 =====
allowed-tools:                    # 工具白名单
  - Read
  - Write
  - Bash(npm *)
  - Bash(git *)

# ===== 元数据 =====
version: 1.0.0
author: your-name
tags: [tag1, tag2]
disabled: false                   # 暂停而不删除
---

flowchart TD
    A[开始创建 Skill] --> B{需要自动触发？}
    B -->|是| C[写好 description + trigger]
    B -->|否| D[设置 disable-model-invocation: true]
    C --> E{涉及敏感操作？}
    D --> E
    E -->|是| F[设置 context: fork<br/>限制 allowed-tools]
    E -->|否| G[使用默认 context]
    F --> H{需要特定模型能力？}
    G --> H
    H -->|是| I[设置 model + effort]
    H -->|否| J[使用默认设置]
    I --> K[完成 Frontmatter]
    J --> K
    style A fill:#4A90D9,color:#fff
    style K fill:#2ECC71,color:#fff

# 示例：代码行数统计
---
name: line-count
description: 统计项目代码行数，按语言分类。输入"统计代码行数"时触发。
trigger: ["代码行数", "line count", "代码统计"]
---

# 示例：API 文档生成
---
name: api-doc-gen
description: >
  从代码自动生成 API 文档。扫描路由定义 → 提取参数和返回值 → 
  生成 Markdown/OpenAPI 文档。当用户说"生成API文档"时触发。
trigger: ["API文档", "接口文档", "api docs", "openapi"]
---

# 示例：多框架组件生成器
---
name: component-gen
description: >
  根据项目技术栈生成前端组件。自动检测 React/Vue/Svelte/Angular，
  使用对应的最佳实践和模板。当用户说"创建组件"时触发。
trigger: ["创建组件", "generate component", "新建组件"]
---

# 示例：批量文件翻译
---
name: batch-translate
description: >
  批量翻译项目中的 Markdown 文件。支持并行处理多个文件，
  保持原始格式和代码块不变。当用户说"批量翻译"时触发。
trigger: ["批量翻译", "translate files", "翻译文档"]
allowed-tools:
  - Read
  - Write
  - Glob
context: fork
---

# 示例：安全部署守卫
---
name: deploy-guard
description: >
  部署前安全检查。运行测试 → 检查敏感信息泄露 → 验证依赖安全性 → 
  确认版本号更新。任何检查失败则阻止部署。当用户说"部署"时触发。
trigger: ["部署", "deploy", "发布上线"]
disable-model-invocation: true
---

# 示例：数据库 Schema 转换器
---
name: schema-adapter
description: >
  在不同 ORM 的 Schema 格式间转换。支持 Prisma ↔ TypeORM ↔ 
  Sequelize ↔ Drizzle 互转。当用户说"转换 Schema"时触发。
trigger: ["转换schema", "schema迁移", "ORM转换"]
---

# 好的 description 公式
"[做什么] + [技术栈/领域] + [何时触发]"

# ❌ 差的写法
description: "代码生成工具"

# ✅ 好的写法
description: >
  从 OpenAPI/Swagger 规范自动生成 Express.js 路由处理器和 TypeScript 类型定义。
  当用户提供 API 规范文件并要求生成后端代码时触发。

# 精确控制 Bash 命令范围
allowed-tools:
  - Read                              # 所有文件读取
  - Bash(git log *)                   # 只允许 git log
  - Bash(npm test *)                  # 只允许 npm test
  - Bash(npx eslint *)                # 只允许 eslint
  - Grep                              # 所有搜索
  - Glob                              # 所有文件匹配

context: fork        # 在独立子代理中执行
model: sonnet        # 使用更快/便宜的模型
effort: medium       # 适中的努力级别

skill-name/
├── SKILL.md              # 始终加载（< 500 行）
├── scripts/              # Claude 按需调用
│   ├── validate.sh       # 输入验证
│   └── format.py         # 输出格式化
└── references/           # 仅在需要时读取
    ├── api-spec.md       # 参考文档
    └── examples.md       # 示例集合

## 参考资料
- 如需了解 API 规范细节，读取 `references/api-spec.md`
- 格式化输出时，先执行 `scripts/format.py`

git add .claude/skills/changelog-gen/
git commit -m "feat: add changelog generator skill"

cp -r .claude/skills/changelog-gen/ ~/.claude/skills/

/skill-creator optimize changelog-gen

# 创建独立的 Skill 仓库
mkdir claude-skill-changelog-gen
cd claude-skill-changelog-gen

# 复制 Skill 文件
cp -r ../your-project/.claude/skills/changelog-gen/* .

# 添加 README 和 package 信息
# 推送到 GitHub
git init && git add . && git commit -m "init"
git remote add origin https://github.com/yourname/claude-skill-changelog-gen.git
git push -u origin main

# 克隆到个人 Skills 目录
git clone https://github.com/yourname/claude-skill-changelog-gen.git \
    ~/.claude/skills/changelog-gen

flowchart TB
    subgraph "Skills 开发全流程"
        A["1. 需求分析<br/>确定 Skill 要解决什么问题"]
        B["2. 目录创建<br/>mkdir -p .claude/skills/name"]
        C["3. 编写 Frontmatter<br/>name + description + trigger"]
        D["4. 编写指令正文<br/>步骤化工作流"]
        E["5. 添加辅助资源<br/>scripts/ references/"]
        F["6. 手动测试<br/>/skill-name"]
        G["7. Eval 自动测试<br/>多场景验证"]
        H["8. 优化迭代<br/>description + 触发精度"]
        I["9. 发布分享<br/>Git / 社区"]
    end

    A --> B --> C --> D --> E --> F
    F -->|"有问题"| D
    F -->|"通过"| G
    G -->|"失败"| H
    H --> D
    G -->|"全部通过"| I

    style A fill:#3498DB,color:#fff
    style I fill:#2ECC71,color:#fff
    style H fill:#E67E22,color:#fff

---
name: pr-review
description: >
  对当前分支的代码变更进行全面审查，覆盖安全漏洞、性能问题、
  代码规范和最佳实践。当用户说"审查代码"、"review PR"、
  "检查代码质量"时自动触发。
trigger:
  - "审查代码"
  - "review"
  - "代码检查"
  - "PR审查"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(git diff *)
  - Bash(git log *)
context: fork
effort: high
version: 1.0.0
tags: [code-review, security, quality]
---

# PR 代码审查

## 工作流程

### 第一步：获取变更范围
1. 运行 `git diff --name-only main...HEAD` 获取变更文件列表
2. 过滤掉无关文件（lock 文件、自动生成文件）
3. 对每个文件运行 `git diff main...HEAD -- <file>` 获取具体变更

### 第二步：逐文件审查
对每个变更文件按以下维度分析：

**安全性（Critical）：**
- SQL 注入、XSS、CSRF 风险
- 硬编码密钥、Token、密码
- 不安全的反序列化
- 未验证的用户输入

**性能（High）：**
- N+1 查询问题
- 不必要的全表扫描
- 内存泄漏风险
- 缺少缓存的热路径

**代码质量（Medium）：**
- 命名不规范
- 重复代码
- 过深的嵌套
- 缺少错误处理

**最佳实践（Low）：**
- 框架惯用法偏离
- 缺少类型注解
- 文档缺失

### 第三步：生成审查报告

输出格式：

```markdown
# 🔍 代码审查报告

## 概要
- 变更文件：X 个
- 发现问题：Critical X / High X / Medium X / Low X
- 总体评价：✅ 可合并 / ⚠️ 需修改 / ❌ 需重做

## Critical 问题
### [SEC-001] SQL 注入风险
- **文件**：`src/api/users.ts:45`
- **代码**：`query("SELECT * FROM users WHERE id = " + id)`
- **建议**：使用参数化查询

## 亮点 🌟
- [值得肯定的代码实践]

## 改进建议
- [非阻断性建议]

安装测试：

```bash
mkdir -p .claude/skills/pr-review
# 将上面的内容保存为 .claude/skills/pr-review/SKILL.md

/review

帮我审查一下当前分支的代码变更

团队其他成员 `git pull` 后立即可用。

### 9.2 跨项目复用

将 Skill 放在用户全局目录：

```bash
# 全局 Skills 目录
mkdir -p ~/.claude/skills/my-skill/
cp -r .claude/skills/changelog-generator ~/.claude/skills/

# 创建专用仓库
mkdir claude-code-skills
cd claude-code-skills
git init

# 每个 Skill 一个目录
cp -r ~/project/.claude/skills/changelog-generator ./
cp -r ~/project/.claude/skills/api-doc-generator ./

# 添加 README
echo "# My Claude Code Skills\n\nInstall with ..." > README.md

git add . && git commit -m "Initial skills collection"
git remote add origin https://github.com/username/claude-code-skills
git push -u origin main

# 安装他人发布的 Skill
claude skill install @username/changelog-generator

# 发布自己的 Skill
claude skill publish ./changelog-generator

{
  "skills": [
    {
      "name": "changelog-generator",
      "source": "git+https://github.com/username/claude-skills#changelog-generator",
      "version": "1.0.0"
    },
    {
      "name": "api-doc-generator",
      "source": "local",
      "path": ".claude/skills/api-doc-generator"
    }
  ]
}

flowchart TD
    A[Skill 未触发] --> B{检查 SKILL.md 位置}
    B -->|位置错误| C[移到 .claude/skills/name/SKILL.md]
    B -->|位置正确| D{检查 frontmatter}
    D -->|格式错误| E[修复 YAML 语法]
    D -->|格式正确| F{检查 trigger}
    F -->|不匹配| G[添加更多触发词]
    F -->|匹配| H{检查 Claude 版本}
    H -->|版本过低| I[升级到 1.0+]
    H -->|版本正常| J[检查是否有多个 Skill 冲突]

# 在 SKILL.md 中记录版本
---
name: changelog-generator
version: "1.2.0"
changelog:
  - "1.2.0: 支持自定义输出格式"
  - "1.1.0: 添加 Conventional Commits 分类"
  - "1.0.0: 初始版本"
---

# 使用 Git tag 管理 Skill 版本
git tag -a "skill/changelog-generator/v1.2.0" -m "Changelog generator v1.2.0"

graph TB
    subgraph "Claude Code 扩展体系"
        A[用户输入] --> B{路由判断}
        B -->|简单工作流| C[Skills 处理]
        B -->|外部工具调用| D[MCP Server 处理]
        B -->|复杂场景| E[Skills + MCP 协作]

        C --> F[纯指令执行]
        D --> G[调用外部 API/工具]
        E --> H[Skill 定义流程]
        H --> I[MCP 提供工具]
        I --> J[整合输出]
    end

    style C fill:#4CAF50,color:#fff
    style D fill:#2196F3,color:#fff
    style E fill:#FF9800,color:#fff