Claude Code Skill开发实战：从零到发布全流程

my-skill/
├── SKILL.md          # 主指令文件（必需）
├── template.md       # 模板文件（可选）
├── examples/
│   └── sample.md     # 示例输出（可选）
├── references/
│   └── api-spec.md   # 参考文档（可选）
└── scripts/
    └── helper.py     # 辅助脚本（可选）

flowchart TD
    A[Claude Code启动] --> B[扫描Skill目录]
    B --> C[加载元数据<br>description字段]
    C --> D{用户消息匹配<br>Skill描述?}
    D -->|是| E[加载完整SKILL.md内容]
    D -->|否| F[仅保留元数据在上下文中]
    E --> G[执行Skill指令]
    G --> H{有!`cmd`注入?}
    H -->|是| I[运行Shell命令<br>替换输出到正文]
    H -->|否| J[直接发送给Claude]
    I --> J
    F --> K[等待下次匹配]

    style A fill:#2563eb,color:#fff
    style D fill:#f59e0b,color:#fff
    style E fill:#10b981,color:#fff

mkdir -p ~/.claude/skills/summarize-changes

cat > ~/.claude/skills/summarize-changes/SKILL.md << 'SKILL_EOF'
---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.
SKILL_EOF

# 进入任意Git项目
cd ~/my-project
claude

> What did I change?

> /summarize-changes

## Environment

```!
node --version
npm --version
git status --short
```

---
# === 基础字段 ===
name: my-skill                    # 显示名称，kebab-case，最长64字符
description: What & when to use   # 触发依据，最长1024字符（最重要的字段）
when_to_use: Extra trigger info   # 补充触发上下文，追加到description

# === 交互控制 ===
argument-hint: "[issue-number]"   # 自动补全提示
arguments: issue branch           # 命名位置参数
disable-model-invocation: true    # 禁止Claude自动触发
user-invocable: false             # 从/菜单隐藏

# === 执行控制 ===
allowed-tools: Read Grep Bash     # 预授权工具列表
model: claude-sonnet-4-6          # 覆盖会话模型
effort: high                      # 覆盖思考预算
context: fork                     # 在子Agent中运行
agent: Explore                    # 子Agent类型

# === 高级特性 ===
hooks:                            # 生命周期钩子
paths: "*.ts,*.tsx"               # 文件路径匹配自动激活
shell: powershell                 # Shell类型（Windows）
---

做什么(What) + 何时用(When) + 产出什么(Output)

# 太模糊 —— 无法判断触发时机
description: Helps with git stuff

# 太技术化 —— 描述实现而非用途
description: Queries /api/v2/sprint endpoint with OAuth2

# 太宽泛 —— 会过度触发
description: Assists with any development task

# 精准触发：领域 + 场景 + 产出
description: >
  Reviews pull requests for security vulnerabilities using OWASP Top 10.
  Use when reviewing PRs that touch authentication, authorization, or
  data handling code. Checks for SQL injection, XSS, and CSRF patterns.

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(npm run build *)
---
Deploy $ARGUMENTS to production:
1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

---
name: fix-issue
description: Fix a GitHub issue by number
arguments: issue_branch
---

---
name: migrate-component
description: Migrate a component from one framework to another
arguments: component from_framework to_framework
---
Migrate the $component component from $from_framework to $to_framework.
Preserve all existing behavior and tests.

Run the analysis script:
```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/analyze.py $ARGUMENTS

---

## 第四步：构建高级Skill——子Agent与隔离执行

当Skill需要大量探索性工作或长时间运行的任务时，使用`context: fork`在隔离的子Agent中执行。

### 4.1 工作原理

```mermaid
sequenceDiagram
    participant U as 用户
    participant M as 主Agent
    participant S as 子Agent(Explore)

    U->>M: /deep-research "认证流程"
    M->>M: 检测context: fork
    M->>S: 创建隔离上下文<br>SKILL.md内容作为Prompt
    Note over S: 无会话历史<br>仅CLAUDE.md + Skill内容
    S->>S: 使用Explore工具集<br>Glob/Grep/Read
    S->>M: 返回研究结果摘要
    M->>U: 展示研究结果

---
name: deep-research
description: >
  Research a codebase topic thoroughly with file references.
  Use when understanding architecture, tracing data flow,
  or investigating unfamiliar code patterns.
context: fork
agent: Explore
allowed-tools: Bash(grep *) Bash(find *)
---

Research "$ARGUMENTS" thoroughly:

1. Use Glob to find relevant files matching the topic
2. Use Grep to search for key terms and patterns
3. Read the most relevant files to understand the implementation
4. Create a structured report with:
   - Summary of findings (2-3 paragraphs)
   - Key files involved (with paths and line numbers)
   - Architecture diagram in Mermaid syntax
   - Open questions or areas needing further investigation

Format the output as Markdown with clear sections.

mkdir -p ~/.claude/skills/pr-review/{scripts,references}

cat > ~/.claude/skills/pr-review/SKILL.md << 'SKILL_EOF'
---
name: pr-review
description: >
  Performs comprehensive code review on a pull request.
  Use when reviewing PRs, checking code quality, identifying bugs,
  or when the user says "review this PR" or "check my changes".
  Covers security, performance, readability, and test coverage.
argument-hint: "[PR-number]"
allowed-tools: Bash(gh *) Read Grep Glob
disable-model-invocation: false
when_to_use: >
  Triggers on: review PR, check code, code review, look at my changes,
  review this pull request, any mention of PR review.
---

# PR Code Review

## PR Context

```!
gh pr view ${PR_NUMBER:-HEAD} --json title,body,author,files,additions,deletions

## Changed Files

```!
gh pr diff ${PR_NUMBER:-HEAD} --name-only

### 5.3 添加参考文档

```bash
cat > ~/.claude/skills/pr-review/references/owasp-checklist.md << 'REF_EOF'
# OWASP Top 10 Quick Reference

| # | Risk | What to Check |
|---|------|---------------|
| A01 | Broken Access Control | Missing auth checks, IDOR, CORS misconfig |
| A02 | Cryptographic Failures | Hardcoded secrets, weak hashing, plaintext storage |
| A03 | Injection | Unparameterized SQL, eval(), template injection |
| A04 | Insecure Design | Missing rate limiting, no input validation |
| A05 | Security Misconfiguration | Default credentials, verbose errors, unused features |
| A06 | Vulnerable Components | Outdated dependencies with known CVEs |
| A07 | Auth Failures | Weak password policies, missing MFA, session fixation |
| A08 | Data Integrity Failures | Untrusted deserialization, unsigned updates |
| A09 | Logging Failures | Missing audit logs, sensitive data in logs |
| A10 | SSRF | Unvalidated URLs, internal service access |

For detailed checklist, refer to [reference.md](reference.md).
REF_EOF

# 在项目目录中
claude

# 方式一：自然语言
> review my latest PR

# 方式二：指定PR号
> /pr-review 42

# 方式三：Claude自动识别场景
> I just opened a PR, can you check it?

### Summary
This PR adds JWT-based authentication to the user API endpoints,
including login, logout, and token refresh flows. The implementation
covers 3 new routes with corresponding middleware.

### Critical Issues 🔴
- **File**: `src/auth/middleware.ts:L28`
- **Issue**: Token secret is read from env but has no fallback validation
- **Fix**: Add startup check: `if (!process.env.JWT_SECRET) throw new Error(...)`

### Warnings 🟡
- **File**: `src/auth/routes.ts:L67`
- **Issue**: refreshTokens array is in-memory, lost on restart
- **Fix**: Use Redis or database for token storage

### Suggestions 🟢
- Consider adding rate limiting to /login endpoint
- Token expiry could be configurable via environment variable

### Verdict
**REQUEST CHANGES** — 1 critical issue must be addressed.

flowchart LR
    A[会话接近<br>上下文上限] --> B[压缩摘要]
    B --> C[重新附加<br>最近触发的Skill]
    C --> D{Token预算}
    D -->|每个Skill<br>前5000 tokens| E[保留]
    D -->|总计<br>25000 tokens| F[从最新Skill<br>开始填充]
    F --> G[超出预算的<br>旧Skill被丢弃]

    style A fill:#ef4444,color:#fff
    style D fill:#f59e0b,color:#fff
    style G fill:#ef4444,color:#fff

// .claude/settings.json
{
  "skillOverrides": {
    "legacy-context": "name-only",  // 仅显示名称，释放描述预算
    "deprecated-skill": "off"        // 完全隐藏
  }
}

# 检查Skill是否被发现
claude
> What skills are available?

# 诊断配置问题
> /doctor

# 查看特定Skill的完整内容（验证渲染结果）
# 直接读取文件确认frontmatter格式

flowchart TD
    A[编写SKILL.md] --> B[手动测试<br>/skill-name]
    B --> C{行为符合预期?}
    C -->|是| D[多场景测试]
    C -->|否| E[分析问题]
    E --> F{触发问题?}
    F -->|未触发| G[优化description<br>添加when_to_use]
    F -->|过度触发| H[缩小description范围<br>或加disable-model-invocation]
    F -->|输出质量差| I[细化指令<br>添加示例和checklist]
    G --> B
    H --> B
    I --> B
    D --> J{覆盖足够?}
    J -->|是| K[发布]
    J -->|否| L[补充边界用例]
    L --> B

    style A fill:#2563eb,color:#fff
    style K fill:#10b981,color:#fff

git add .claude/skills/
git commit -m "Add code review and deploy skills"

# 1. 创建Plugin仓库结构
my-plugin/
├── SKILL.md          # Plugin描述（可选）
├── skills/
│   ├── pr-review/
│   │   └── SKILL.md
│   └── deploy/
│       └── SKILL.md
└── package.json      # Plugin元数据

# 2. 注册为Plugin市场
claude
> /plugin marketplace add your-org/your-plugin-repo

# 3. 或直接安装
> /plugin install plugin-name@marketplace-name

mkdir -p ~/.claude/skills/codebase-visualizer/scripts

---
name: codebase-visualizer
description: >
  Generate an interactive collapsible tree visualization of your codebase.
  Use when exploring a new repo, understanding project structure,
  or identifying large files.
allowed-tools: Bash(python3 *)
---

# Codebase Visualizer

Generate an interactive HTML tree view of the project.

## Usage

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .

将Python脚本放在`scripts/visualize.py`中，使用`${CLAUDE_SKILL_DIR}`确保路径正确。

---

## 第十步：权限控制与安全实践

### 10.1 Skill访问控制

三种方式限制Claude调用Skill：

```bash
# 方式一：在Skill中设置
disable-model-invocation: true

# 方式二：通过权限规则
# .claude/settings.json
{
  "permissions": {
    "allow": ["Skill(commit)", "Skill(review-pr *)"],
    "deny": ["Skill(deploy *)"]
  }
}

# 方式三：完全禁止Skill工具
# /permissions deny Skill

flowchart TD
    subgraph 创建阶段
        A[确定Skill用途] --> B[选择存放位置<br>个人/项目/插件]
        B --> C[创建目录和SKILL.md]
        C --> D[编写description<br>三要素公式]
        D --> E[编写指令正文<br>具体可操作]
    end

    subgraph 增强阶段
        E --> F{需要动态数据?}
        F -->|是| G[添加!`cmd`注入]
        F -->|否| H{需要隔离执行?}
        G --> H
        H -->|是| I[设置context: fork]
        H -->|否| J{需要捆绑资源?}
        I --> J
        J -->|是| K[添加scripts/references/]
        J -->|否| L[配置allowed-tools]
        K --> L
    end

    subgraph 测试阶段
        L --> M[手动调用测试]
        M --> N{触发正确?}
        N -->|未触发| O[优化description]
        N -->|过度触发| P[添加disable-model-invocation]
        N -->|质量不佳| Q[细化指令和示例]
        O --> M
        P --> M
        Q --> M
    end

    subgraph 发布阶段
        N -->|通过| R{分发方式}
        R -->|团队| S[提交到Git仓库]
        R -->|社区| T[创建Plugin]
        R -->|企业| U[托管设置分发]
    end

    style A fill:#2563eb,color:#fff
    style M fill:#f59e0b,color:#fff
    style R fill:#10b981,color:#fff

---
name: your-skill-name
description: >
  [做什么 — 一句话描述核心功能].
  Use when [何时用 — 列出2-3个触发场景].
  [产出 — 说明输出格式或效果].
when_to_use: >
  Triggers on: [关键词1], [关键词2], [自然语言触发示例].
argument-hint: "[参数提示]"
allowed-tools: [工具列表]
disable-model-invocation: false
---

# [Skill名称]

## Context
[当前状态或动态注入的数据]
!`relevant-command-here`

## Instructions
[具体、可操作的步骤列表]

1. Step one — use the [Tool] to [action]
2. Step two — check [specific criteria]
3. Step three — generate [output format]

## Output Format
[期望的输出结构]

## Error Handling
- If [error condition]: [fallback action]
- If [missing data]: [ask user or skip]

## Guidelines
- [规则1]
- [规则2]
- [注意事项]

# 差
Review the code and suggest improvements.

# 好
Use the Read tool to load each changed file. Check against these criteria:
- No hardcoded secrets (API keys, passwords, tokens)
- All public functions have error handling
- SQL queries use parameterized statements
For each issue: file path, line number, severity, fix recommendation.