Claude Code Skills 开发实战：从零创建自定义 Skill 到发布

claude --version
# 确保输出 >= 2.1.145

graph TD
    A[用户输入 / 提问] --> B{Claude 检查可用 Skills 列表}
    B -->|description 匹配| C[加载 Skill 元数据<br/>name + description ~100 tokens]
    C --> D[读取 SKILL.md 正文<br/>执行指令]
    D -->|需要参考文件| E[按需加载 references/<br/>scripts/ 等资源]
    D -->|任务简单| F[直接执行并返回结果]
    E --> G[使用完整资源完成任务]
    F --> H[输出结果]
    G --> H

    style C fill:#22d3ee,stroke:#0e7490,color:#000
    style D fill:#34d399,stroke:#047857,color:#000
    style E fill:#a78bfa,stroke:#6d28d9,color:#fff

graph LR
    subgraph 优先级从高到低
        E[Enterprise<br/>企业管理配置]
        P[Personal<br/>~/.claude/skills/]
        R[Project<br/>.claude/skills/]
        PL[Plugin<br/>插件内 skills/]
    end
    E --> P --> R --> PL

    style E fill:#fb7185,stroke:#be123c,color:#fff
    style P fill:#fbbf24,stroke:#92400e,color:#000
    style R fill:#34d399,stroke:#047857,color:#000
    style PL fill:#94a3b8,stroke:#334155,color:#fff

my-skill/
├── SKILL.md              # 主指令文件（必须）
├── template.md           # 模板文件（可选）
├── examples/
│   └── sample.md         # 示例输出（可选）
├── scripts/
│   └── validate.sh       # 可执行脚本（可选）
├── references/
│   ├── api-guide.md      # 参考资料（可选）
│   └── best-practices.md
└── assets/
    └── logo.svg          # 静态资源（可选）

---
# === 基础字段 ===
name: my-skill                    # 显示名，省略则用目录名
description: |                    # 核心字段：Claude 据此判断是否触发
  一句话说明做什么。触发词：X、Y、Z。
  当用户需要 A、B、C 时使用此技能。

# === 触发控制 ===
when_to_use: |                    # 补充触发上下文（计入 1536 字符上限）
  用户说"帮我部署"、"发布到生产"时触发。
disable-model-invocation: true    # true = 禁止 Claude 自动触发，仅 /手动调用
user-invocable: true              # false = 从 / 菜单隐藏（背景知识型）

# === 参数 ===
argument-hint: "[issue-number]"   # 自动补全时显示的参数提示
arguments: "issue-number"         # 命名参数，可在正文中用 $issue-number 引用

# === 执行控制 ===
context: fork                     # 在子 Agent 中运行（隔离上下文）
agent: general-purpose            # 子 Agent 类型（需 context: fork）
model: claude-sonnet-4-6          # 指定运行模型
effort: high                      # 努力级别：low/medium/high/xhigh/max
allowed-tools: "Read Grep Bash"   # 预授权工具列表

# === 路径过滤 ===
paths: "src/**/*.py,tests/**/*.py" # 仅在匹配路径时激活

# === 其他 ===
shell: bash                       # shell 类型（bash 或 powershell）
---

# frontmatter 中定义命名参数
arguments: "filename format"

<!-- 正文中使用 -->
处理文件 $filename，输出格式为 $format。

## 当前变更
!\`git diff HEAD\`

## 当前分支
!\`git branch --show-current\`

## 文件列表
\`\`\`!
ls -la src/
\`\`\`

# 创建个人级 Skill
mkdir -p ~/.claude/skills/api-doc-gen/references
mkdir -p ~/.claude/skills/api-doc-gen/templates

---
name: api-doc-gen
description: |
  扫描项目 API 路由并生成标准化 Markdown API 文档。
  触发词："生成 API 文档"、"API 文档"、"接口文档"、"接口文档生成"、"API reference"。
  当用户需要生成、更新或审查 API 文档时使用此技能。
  支持扫描 Express.js、Fastify、Koa 路由定义。
argument-hint: "[output-path]"
arguments: "output-path"
disable-model-invocation: false
---

# API 文档生成技能

## 角色定义

你是一位专业的 API 文档工程师。根据项目源代码中的路由定义，自动生成结构清晰、信息完整的 API 文档。

## 工作流程

### Step 1：识别框架

扫描项目的 `package.json`，判断使用的 Web 框架：
- 包含 `express` → Express.js 模式
- 包含 `fastify` → Fastify 模式
- 包含 `koa` / `@koa/router` → Koa 模式
- 无法识别 → 询问用户确认

### Step 2：发现路由文件

使用 Glob 查找路由定义文件：
- `src/routes/**/*.{js,ts}`
- `src/**/*route*.{js,ts}`
- `src/**/*controller*.{js,ts}`
- `app.{js,ts}`（根路由注册）

### Step 3：提取路由信息

对每个路由文件，提取以下信息：
1. HTTP 方法（GET/POST/PUT/DELETE/PATCH）
2. 路径（含路径参数，如 `/users/:id`）
3. 中间件链（认证、校验等）
4. 请求参数（query、body、params）
5. 响应格式（从 res.json 推断）
6. 描述注释（JSDoc @description 或行上注释）

### Step 4：生成文档

按照 `templates/api-doc-template.md` 的格式生成文档。

### Step 5：安全审查

在文档末尾附加安全审查清单：
- 标记缺少认证中间件的路由
- 标记缺少输入校验的 POST/PUT/PATCH 路由
- 标记可能存在 SQL 注入风险的查询拼接

## 输出路径

- 如果用户提供了 `$output-path`，保存到指定位置
- 否则保存到 `docs/api-reference.md`

## 参考资源

框架特定的路由模式识别规则，见 `references/framework-patterns.md`。

# 框架路由模式参考

## Express.js 路由模式

```javascript
// 模式 1：app 直接挂载
app.get('/users', handler)
app.post('/users', handler)

// 模式 2：Router 模块
const router = express.Router()
router.get('/:id', handler)
app.use('/users', router)

// 模式 3：路由文件导出
module.exports = (app) => {
  app.route('/items')
    .get(handler)
    .post(handler)
}

// 模式 1：直接注册
fastify.get('/users', { schema: {...} }, handler)

// 模式 2：插件模式
module.exports = async (fastify) => {
  fastify.post('/users', handler)
}

// @koa/router
const router = new Router()
router.get('/users', handler)
router.post('/users/:id', handler)
app.use(router.routes())

### 4.5 创建输出模板

`templates/api-doc-template.md`：

````markdown
# API Reference

> 自动生成于 {date} | 框架：{framework} | 路由总数：{count}

## 目录

- [认证](#authentication)
- {group-toc}

## 认证

{authentication-section}

---

{group-sections}

---

## 安全审查

| 路由 | 问题 | 严重程度 |
|------|------|----------|
| {security-findings} |
````

### 4.6 最终目录结构

---

## 五、测试与调试

### 5.1 即时生效机制

Claude Code 实时监控 Skill 目录变更。**创建或编辑 Skill 后无需重启**，下一个对话轮次即可生效。

```bash
# 创建 Skill 后直接测试
claude
# 在对话中输入：
> /api-doc-gen
# 或触发自动匹配：
> 帮我生成这个项目的 API 文档

flowchart LR
    A[用户输入] --> B{包含 /skill-name?}
    B -->|是| C[直接加载 SKILL.md<br/>100% 触发]
    B -->|否| D{description 匹配?}
    D -->|是| E[Claude 决定是否加载]
    D -->|否| F[不触发]
    E -->|任务复杂| G[加载并执行]
    E -->|任务简单<br/>Claude 能独立完成| H[不加载<br/>直接用内置能力处理]

    style C fill:#34d399,stroke:#047857,color:#000
    style G fill:#34d399,stroke:#047857,color:#000
    style H fill:#fbbf24,stroke:#92400e,color:#000

---
name: deep-analysis
description: 深度代码分析，生成架构报告。
context: fork
agent: general-purpose
effort: high
---

---
name: deploy-check
hooks:
  PreToolUse:
    - match: "Bash"
      command: "echo 'Deploy skill activated'"
  PostToolUse:
    - match: "Bash"
      command: "echo 'Command completed'"
---

---
name: quick-refactor
model: claude-sonnet-4-6     # 使用更快的模型
effort: low                   # 快速响应模式
allowed-tools: "Read Edit Grep Bash"  # 预授权工具，无需逐一确认
---

---
name: python-style
paths: "src/**/*.py,tests/**/*.py,*.py"
---

graph TB
    subgraph "Claude Code 扩展体系"
        SK[Skill<br/>指令文档]
        MCP[MCP Server<br/>工具服务器]
        SUB[Subagent<br/>独立 Agent]
        CMD[CLAUDE.md<br/>项目配置]
    end

    SK -->|"复杂度低<br/>纯文本指令"| MCP
    SK -->|"需要隔离<br/>可 fork 为"| SUB
    CMD -->|"增长为流程<br/>可提取为"| SK

    style SK fill:#fbbf24,stroke:#92400e,color:#000
    style MCP fill:#a78bfa,stroke:#6d28d9,color:#fff
    style SUB fill:#22d3ee,stroke:#0e7490,color:#000
    style CMD fill:#94a3b8,stroke:#334155,color:#fff

# 如果有 skill-creator 插件
python -m scripts.package_skill ~/.claude/skills/api-doc-gen
# 输出：api-doc-gen.skill

# 克隆 Skill 仓库
git clone https://github.com/yourname/claude-skills ~/my-skills

# 启动 Claude Code 时引入
claude --add-dir ~/my-skills

sequenceDiagram
    participant U as 用户
    participant C as Claude Code
    participant S1 as Skill A: 代码扫描
    participant S2 as Skill B: 报告生成

    U->>C: /scan-and-report src/
    C->>S1: 触发代码扫描 Skill
    S1->>S1: 扫描路由、依赖、安全风险
    S1-->>C: 返回结构化分析数据
    C->>S2: 触发报告生成 Skill
    S2->>S2: 将分析数据格式化为 HTML 报告
    S2-->>C: 输出 report.html
    C-->>U: 扫描完成，报告已生成

Skill (指令) → "调用 GitHub MCP 获取 PR 列表" → MCP Server (执行) → 结果返回 → Skill 继续处理

<!-- SKILL.md 正文 -->
## 框架特定规则
读取 `references/express.md` 获取 Express.js 路由模式。
读取 `references/fastify.md` 获取 Fastify 路由模式。
仅在使用对应框架时才读取相应文件。

# 差：过于宽泛
description: "Helps with API documentation."

# 好：具体且有触发词
description: |
  扫描项目源代码中的 API 路由定义，自动生成标准化 Markdown API 文档。
  触发词："生成 API 文档"、"接口文档"、"API reference"、"文档化接口"。
  当用户提到 API 文档、接口文档、路由文档时使用。
  支持识别 Express.js、Fastify、Koa 框架路由。

# 差：命令式
MUST scan all files. MUST use Express pattern. MUST check security.

# 好：解释原因
扫描所有路由文件以确保文档完整性——遗漏的路由意味着消费者无法发现该接口。
优先识别 Express 模式因为这是项目的主要框架。
安全审查帮助团队在部署前发现潜在风险。

# 实时获取当前状态
!\`git diff HEAD --name-only\`
!\`cat package.json | grep -E "express|fastify|koa"\`

# 根据实时数据决策，而非让 Claude 去猜

graph TD
    A["1. mkdir -p ~/.claude/skills/api-doc-gen"] --> B["2. 编写 SKILL.md"]
    B --> C["3. 创建 references/ 参考文件"]
    C --> D["4. 创建 templates/ 模板文件"]
    D --> E["5. 在任意 Express 项目中测试"]
    E --> F["6. 输入 /api-doc-gen 触发"]
    F --> G["7. 检查生成的 docs/api-reference.md"]
    G --> H["8. 迭代优化 description 触发词"]
    H --> I["9. 添加路径过滤 paths 字段"]
    I --> J["10. 打包发布"]

    style A fill:#22d3ee,stroke:#0e7490,color:#000
    style F fill:#fbbf24,stroke:#92400e,color:#000
    style J fill:#34d399,stroke:#047857,color:#000