Tutorial ｜构建 Skill¶

难度：⭐⭐ 时间：~1h 前置：基本 Claude Code 使用产物：自定义 /my-skill 命令

1. Skill 是什么¶

Skill = 用户自定义的"快捷命令" - Markdown 文件定义 - /<skill-name> 触发 - 可注入 prompt - 可执行代码

2. Skill vs Command vs Plugin¶

维度	Skill	Command	Plugin
位置	`skills/`	`commands/`	plugin 内
触发	`/skill-name`	`/cmd`	`/cmd`
复杂度	简单	简单	复杂
分发	个人	个人	团队

3 种 —— Skill 最简单。

3. 2 种 Skill 格式¶

3.1 简单 Skill（prompt 注入）¶

---
name: code-review
description: Triggered when user asks for code review
---

# Code Review

When reviewing code, follow this checklist:
- Security
- Performance
- Style
- Tests

prompt 注入。

3.2 复杂 Skill（含代码）¶

---
name: deploy
description: Deploy the project
allowed-tools: Bash, Read
---

# Deploy

## Steps

1. Check git status
2. Run tests
3. Build
4. Deploy

Run: !bash
\`\`\`bash
npm test
npm run build
npm run deploy
\`\`\`

含代码执行。

4. 实战：4 个 Skill¶

4.1 Skill 1: Code Review¶

mkdir -p ~/.claude/skills/code-review
cat > ~/.claude/skills/code-review/SKILL.md <<'EOF'
---
name: code-review
description: Triggered when user asks for code review
---

# Code Review

When user asks for code review:

1. Read the relevant files
2. Check for:
   - Security vulnerabilities
   - Performance issues
   - Style violations
   - Missing tests
3. Provide specific feedback with line numbers
4. Suggest concrete improvements

Output format:
- Issue: <description>
- Severity: critical/medium/low
- Location: file:line
- Fix: <suggested code change>
EOF

完整。

4.2 Skill 2: Test Generator¶

---
name: test-gen
description: Generate unit tests
---

# Test Generator

When user asks to write tests:

1. Read source file
2. Identify exported functions
3. For each function, generate:
   - Happy path test
   - Edge cases
   - Error cases
4. Use project's test framework
5. Place in conventional test location

3 步。

4.3 Skill 3: Commit Message¶

---
name: commit-msg
description: Generate commit message
---

# Commit Message Generator

When user runs /commit:

1. Check git status
2. Check git diff
3. Identify changes
4. Generate commit message:
   - type (docs/feat/fix/chore)
   - subject (50 chars)
   - body (what + why)
5. NO Co-Authored-By Claude
6. NO emoji in subject

Ask user to confirm before commit.

commit 工具。

4.4 Skill 4: Refactor Helper¶

---
name: refactor
description: Refactor code
---

# Refactor Helper

When user asks to refactor:

1. Read the file
2. Identify code smells
3. Suggest refactorings:
   - Extract function
   - Rename for clarity
   - Reduce complexity
   - Remove duplication
4. Provide before/after code
5. Run tests after each change

重构助手。

5. 3 步使用 Skill¶

5.1 创建¶

mkdir -p ~/.claude/skills/<skill-name>
# 或项目级
mkdir -p .claude/skills/<skill-name>

位置。

5.2 写 SKILL.md¶

---
name: <skill-name>
description: <when to trigger>
---

# <Title>
<instructions>

格式。

5.3 触发¶

# 在 Claude Code 中
> /<skill-name>

# 或用户说"按 <skill-name> 模式"
> Run code-review on src/auth.ts

2 种触发。

6. SKILL.md 详细字段¶

---
name: code-review       # 必填
description: ...        # 必填
allowed-tools: Bash,Read  # 可选：允许的工具
model: sonnet           # 可选：模型
---

5 字段。

7. 高级特性¶

7.1 `$ARGUMENTS`¶

---
name: search
description: Search the codebase
---

# Search

Search the codebase for: $ARGUMENTS

Use Grep / Glob aggressively.

$ARGUMENTS 替换用户输入。

7.2 bash 代码块¶

Run tests:
!bash
npm test

!bash 块。

7.3 引用其他文件¶

Read @~/.claude/agents/reviewer.md and apply its guidelines.

@file 引用。

8. 3 层 Skill 分发¶

8.1 个人级¶

~/.claude/skills/

个人。

8.2 项目级¶

.claude/skills/

项目。

8.3 Plugin 内¶

<plugin>/skills/

Plugin。

9. 调试 Skill¶

9.1 不触发¶

检查 SKILL.md 路径
检查 frontmatter 格式
重新启动 Claude Code

9.2 触发但无效¶

简化 description
加更明确指令
测试 prompt

9.3 与其他 skill 冲突¶

description 更具体
命名区分

10. 5 个最佳实践¶

description 清晰 —— 决定触发
指令具体 —— 步骤明确
输出格式 —— 强制结构
小而专 —— 一个 skill 一个目的
示例 prompt —— 给具体例子

5 条。

11. 完整示例：Refactor Skill¶

---
name: refactor
description: Refactor code following best practices
allowed-tools: Read, Grep, Glob, Edit
---

# Refactor

When user asks to refactor code:

1. **Read** the file
2. **Analyze**:
   - Long functions (> 50 lines)
   - Deep nesting (> 3 levels)
   - Duplicate code
   - Magic numbers
   - Unclear names
3. **Suggest** refactorings (in priority order):
   - Extract function
   - Extract constant
   - Rename
   - Simplify conditionals
   - Remove dead code
4. **Implement** one at a time
5. **Test** after each change
6. **Verify** no behavior change

Output format:
- Finding: <description>
- Severity: high/medium/low
- Location: file:line
- Refactoring: <technique>
- Before/after: <code>

完整。

12. 下一步¶

写第一个 skill
用 /<name> 触发
调优

Tutorial ｜ 构建 Skill¶