Claude Code Skill质量工程：从描述优化到触发率评估全实战

flowchart TD
    A[会话启动] --> B[扫描 Skill 目录]
    B --> C[仅加载 name + description<br/>~100 tokens/skill]
    C --> D[用户发送消息]
    D --> E{Claude 匹配 description<br/>与用户意图?}
    E -->|匹配| F[加载完整 SKILL.md 内容<br/>~1000-5000 tokens]
    E -->|不匹配| G[不加载任何内容<br/>0 tokens 消耗]
    F --> H[按需加载支持文件<br/>references/scripts]
    H --> I[执行 Skill 指令]

    style E fill:#f9f,stroke:#333,stroke-width:2px
    style G fill:#9f9,stroke:#333

---
name: my-skill                    # 显示名称（默认取目录名）
description: >                    # 触发描述（最重要）
  What this skill does and when.
when_to_use: >                    # 补充触发上下文
  Additional trigger phrases.
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          # Skill 执行时使用的模型
effort: high                      # 推理深度覆盖
context: fork                     # 在子代理中运行
agent: Explore                    # 指定子代理类型
hooks: {}                         # Skill 生命周期钩子
paths: "src/**/*.py"              # 路径匹配激活
shell: bash                       # Shell 类型
---

flowchart LR
    A{谁决定何时运行?} -->|"我决定"| B["disable-model-invocation: true<br/>如 /deploy, /commit"]
    A -->|"Claude 决定"| C["默认行为<br/>如 lint-after-edit"]
    A -->|"纯背景知识"| D["user-invocable: false<br/>如 legacy-system-context"]

    style B fill:#f96,stroke:#333
    style C fill:#6f9,stroke:#333
    style D fill:#69f,stroke:#333

mkdir -p .claude/skills/deploy-prod

---
name: deploy-prod
description: >
  Deploy the application to production environment.
  Use ONLY when the user explicitly asks to deploy to production,
  push to prod, or release to production.
when_to_use: >
  Triggers on: "deploy to production", "push to prod",
  "release to production", "deploy prod"
disable-model-invocation: true
allowed-tools: Bash(docker *) Bash(kubectl *) Bash(git push *)
argument-hint: "[version-tag]"
---

## Deploy Production Workflow

Deploy version $ARGUMENTS to production:

1. **Pre-flight checks**
   Run `git status --porcelain` and abort if uncommitted changes exist.
   Run `docker build --dry-run .` to validate the build.

2. **Build and tag**
   Build the Docker image:
   ```bash
   docker build -t myapp:$ARGUMENTS .
   docker tag myapp:$ARGUMENTS myapp:latest
   ```

3. **Push to registry**
   ```bash
   docker push myapp:$ARGUMENTS
   docker push myapp:latest
   ```

4. **Deploy**
   ```bash
   kubectl set image deployment/myapp myapp=myapp:$ARGUMENTS
   kubectl rollout status deployment/myapp --timeout=300s
   ```

5. **Verify**
   Check health endpoint and report status.
   If rollout fails, run `kubectl rollout undo deployment/myapp`.

[动词] + [任务描述] + [触发条件]

description: "A helpful skill for working with pull requests"

description: >
  Summarize pull request changes and generate PR descriptions.
  Use when the user asks to create a PR, write a PR description,
  summarize a pull request, or generate a PR body.
when_to_use: >
  Also triggers on: "pr summary", "pull request", "what changed",
  "describe this branch", "review my changes"

description: >
  Summarize pull request changes with live diff data and generate
  PR descriptions. Use when the user asks to create a PR, write
  a PR description, summarize changes, or review a pull request.
when_to_use: >
  Triggers on: "pr summary", "pull request", "what changed",
  "describe this branch", "review my changes", "pr body"
context: fork
agent: Explore
allowed-tools: Bash(gh pr *)
---
## PR Context
- Diff: !`gh pr diff`
- Files: !`gh pr diff --name-only`
- Comments: !`gh pr view --comments`

Generate a PR summary with:
- One paragraph overview
- Bullet list of changes
- Test plan checklist

when_to_use: >
  Triggers when user says: "run tests", "check if tests pass",
  "run the test suite", "verify tests", "are tests green",
  "test coverage", "run pytest"

sequenceDiagram
    participant U as 用户
    participant CC as Claude Code
    participant S as Shell
    participant C as Claude

    U->>CC: /pr-summary
    CC->>CC: 匹配 Skill description
    CC->>S: 执行 !`gh pr diff`
    S-->>CC: 返回 diff 输出
    CC->>S: 执行 !`gh pr view --comments`
    S-->>CC: 返回评论内容
    CC->>C: 发送渲染后的 SKILL.md<br/>（含实际 diff 数据）
    C-->>U: 基于 live 数据的 PR 总结

当前工作区差异：
!`git diff HEAD`

当前分支名：
!`git branch --show-current`

```!
node --version
npm --version
git status --short
git log --oneline -5
```

mkdir -p ~/.claude/skills/live-review

---
name: live-review
description: >
  Perform a real-time code review of current uncommitted changes.
  Use when the user asks to review changes, check their code,
  review the diff, or asks "does this look right?"
allowed-tools: Read Grep Bash(git *)
---

## Current Working Tree

### Changed files
!`git diff --name-only`

### Full diff
!`git diff HEAD`

### Recent commits for context
!`git log --oneline -10`

## Review Instructions

Review the changes above across these five dimensions:

### 1. Correctness (CRITICAL)
- Logic errors or off-by-one bugs
- Null/undefined handling
- Edge case coverage

### 2. Security (CRITICAL)
- Input validation gaps
- SQL injection / XSS risks
- Hardcoded secrets or credentials

### 3. Performance (MAJOR)
- Algorithm complexity issues
- N+1 query patterns
- Unnecessary re-renders or computations

### 4. Code Quality (MINOR)
- Naming conventions
- Function length
- DRY violations

### 5. Suggestions (INFO)
- Alternative approaches
- Documentation improvements

## Output Format

For each finding, provide:
- **[SEVERITY]** Title
- File: `path/to/file:line_number`
- Issue: description
- Fix: code example

If no issues found, highlight good practices observed.

{
  "disableSkillShellExecution": true
}

my-skill/
├── SKILL.md              # 核心指令（必需，≤500行）
├── reference.md          # 详细参考文档（按需加载）
├── examples.md           # 输出示例（按需加载）
├── templates/
│   └── output.html       # 输出模板
├── scripts/
│   ├── validate.sh       # 可执行脚本
│   └── analyze.py        # 数据分析脚本
└── tests/
    └── test-cases.md     # 测试场景描述

## Additional Resources

- For complete API parameter reference, see [reference.md](reference.md)
- For example outputs showing expected format, see [examples.md](examples.md)
- For the validation script, run `bash ${CLAUDE_SKILL_DIR}/scripts/validate.sh`

mkdir -p ~/.claude/skills/deep-research

---
name: deep-research
description: >
  Research a topic thoroughly across the codebase using file search,
  code analysis, and cross-reference. Use when the user asks to
  research, investigate, analyze architecture, or understand how
  something works in the codebase.
context: fork
agent: Explore
argument-hint: "[topic]"
allowed-tools: Read Glob Grep
---

## Research Task

Research the following topic thoroughly: $ARGUMENTS

## Research Methodology

1. **Discovery Phase**
   - Use Glob to find all relevant files matching the topic
   - Use Grep to search for key terms and patterns
   - Identify the core modules and their relationships

2. **Analysis Phase**
   - Read the most relevant files completely
   - Trace data flow and control flow
   - Identify design patterns and architectural decisions

3. **Synthesis Phase**
   - Summarize findings with specific file references
   - Map component dependencies
   - Identify potential issues or improvement areas

## Output Format

### Summary
2-3 sentence overview of findings.

### Key Files
- `path/to/file:line` — what this file does

### Architecture
Description of how components relate.

### Recommendations
Any issues or improvements discovered.

mkdir -p ~/.claude/skills/fix-issue

---
name: fix-issue
description: >
  Fix a GitHub issue by number. Use when the user asks to fix,
  resolve, or address a GitHub issue.
disable-model-invocation: true
argument-hint: "[issue-number]"
allowed-tools: Bash(gh *) Read Grep Edit Write
---

## Fix GitHub Issue $ARGUMENTS

### Step 1: Read the issue

```bash
gh issue view $ARGUMENTS

**调用**：`/fix-issue 42` — 参数 `42` 替换所有 `$ARGUMENTS` 占位符。

**多参数示例**：`/migrate SearchBar React Vue` — 需要 frontmatter 中声明 `arguments: [component, from, to]`，然后 `$component` = SearchBar、`$from` = React、`$to` = Vue。

---

## 第八章：路径匹配与条件激活

### 8.1 `paths` 字段

`paths` 字段允许你限定 Skill 仅在操作特定路径的文件时激活。这对 monorepo 或多语言项目特别有用：

```yaml
---
name: python-linter
description: Run Python linter on modified files
paths: "src/**/*.py, tests/**/*.py"
allowed-tools: Bash(ruff *) Read
---

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy-prod": "off",
    "code-reviewer": "user-invocable-only"
  }
}

.claude/skills/
├── smart-commit/
│   └── SKILL.md          # 智能提交
├── pr-ready/
│   └── SKILL.md          # PR 就绪检查 + 描述生成
└── branch-status/
    └── SKILL.md          # 分支状态报告

# .claude/skills/smart-commit/SKILL.md
---
name: smart-commit
description: >
  Generate a conventional commit message from staged changes and
  create the commit. Use when the user asks to commit, create a
  commit message, stage and commit, or make a commit.
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *) Bash(git diff *)
---

## Staged Changes Analysis

### Status
!`git status --short`

### Staged Diff
!`git diff --cached`

### Recent Commit Style
!`git log --oneline -5`

## Instructions

1. Analyze the staged diff above
2. Determine the commit type:
   - `feat:` new feature
   - `fix:` bug fix
   - `refactor:` code restructuring
   - `docs:` documentation only
   - `test:` test additions
   - `chore:` build/tooling changes
3. Identify the scope (module or component affected)
4. Generate commit message following these rules:
   - Subject: `<type>(<scope>): <imperative description>` (≤50 chars)
   - Body: explain WHY, not what (wrap at 72 chars)
   - Footer: breaking changes, issue references
5. Create the commit with the generated message
6. Report what was committed

If no changes are staged, run `git status` and ask the user
what to stage before proceeding.

# .claude/skills/pr-ready/SKILL.md
---
name: pr-ready
description: >
  Check if the current branch is ready for a pull request and
  generate the PR description. Use when the user asks to create
  a PR, check PR readiness, or generate a PR body.
disable-model-invocation: true
allowed-tools: Bash(git *) Bash(gh pr *)
---

## Branch Context

### Branch name
!`git branch --show-current`

### Commits since main
!`git log main..HEAD --oneline`

### Full diff against main
!`git diff main...HEAD --stat`

### Test status
!`npm test 2>&1 | tail -20 || echo "No test command found"`

## PR Readiness Checklist

Check each item and report status:

1. [ ] All commits follow conventional format
2. [ ] No debug code or console.log remaining
3. [ ] Tests are passing
4. [ ] No merge conflicts with main
5. [ ] No large files accidentally committed

## PR Description Template

Generate the PR description:

## Summary
[One paragraph, no marketing language]

## Changes
- [One bullet per logical change, not per commit]

## Test plan
- [ ] [Specific test a reviewer can run]

## Screenshots (if applicable)

## Breaking changes
[None / List any breaking changes]

# .claude/skills/branch-status/SKILL.md
---
name: branch-status
description: >
  Show current branch status including uncommitted changes,
  commits ahead/behind main, and stashed changes. Use when the
  user asks about branch status, what changed, or current state.
allowed-tools: Bash(git *)
---

## Branch Status Report

### Current branch
!`git branch --show-current`

### Uncommitted changes
!`git status --short`

### Ahead/behind main
!`git rev-list --left-right --count main...HEAD`

### Stashed changes
!`git stash list`

### Recent commits
!`git log --oneline -10 --decorate --graph`

## Instructions

Provide a concise status summary:
1. Which branch you're on
2. How many uncommitted changes (staged vs unstaged)
3. How far ahead/behind main
4. Any stashes
5. Recent commit activity

Highlight anything that needs attention:
- Uncommitted changes in critical files
- Branch significantly behind main
- Stale branches

flowchart LR
    A[编码完成] --> B["/branch-status<br/>查看当前状态"]
    B --> C["/smart-commit<br/>生成规范提交"]
    C --> D[更多修改?]
    D -->|是| A
    D -->|否| E["/pr-ready<br/>PR就绪检查"]
    E --> F[创建 Pull Request]

    style A fill:#69f,stroke:#333
    style C fill:#f96,stroke:#333
    style E fill:#9f6,stroke:#333

flowchart TD
    A[编写 Skill] --> B[准备 10 条测试输入]
    B --> C{每条输入<br/>是否触发?}
    C -->|是| D[记录命中]
    C -->|否| E[记录失败]
    D --> F{命中率 ≥ 80%?}
    E --> F
    F -->|是| G[✅ 通过]
    F -->|否| H[优化 description]
    H --> B

    style G fill:#6f9,stroke:#333
    style H fill:#f96,stroke:#333

flowchart TB
    A[Enterprise<br/>企业级<br/>全员强制] --> B[Plugin<br/>插件级<br/>按需安装]
    B --> C[Personal<br/>个人级<br/>~/.claude/skills/]
    C --> D[Project<br/>项目级<br/>.claude/skills/]

    A -.- E["Managed Settings<br/>组织管理员配置"]
    B -.- F["/plugin install<br/>或 curl 安装"]
    C -.- G["个人目录<br/>跨项目可用"]
    D -.- H["Git 版本控制<br/>团队共享"]

# 从插件市场安装
/plugin install frontend-design@anthropic-agent-skills

# 添加第三方市场
/plugin marketplace add agensi

# curl 一键安装
mkdir -p ~/.claude/skills && curl -sL https://www.agensi.io/api/install/SKILL_SLUG | tar xz -C ~/.claude/skills/