Skill Guide¶

重要性：⭐⭐ 目标读者：所有用户关联：tutorials/build-skill.md

1. 概览¶

Skill = 用户自定义快捷命令（Markdown）

vs Plugin / Command： - 简单（一个 Markdown） - 触发：/skill-name 或描述匹配 - 分发：个人 / 项目

2. 2 种 Skill 格式¶

2.1 简单 Skill（prompt 注入）¶

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

# Code Review

When user asks for code review:

1. Read the file
2. Check security, performance, style
3. Output: file:line issue + severity + fix

prompt。

2.2 复杂 Skill（含工具）¶

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

# Deploy

Run: !bash
npm test
npm run build

tool。

3. 3 步使用¶

3.1 创建¶

mkdir -p ~/.claude/skills/code-review
# 或项目级
mkdir -p .claude/skills/code-review

创建。

3.2 写 SKILL.md¶

---
name: code-review
description: ...
---

# Title
<instructions>

写。

3.3 触发¶

> /code-review
# 或
> Run code-review on src/auth.ts

触发。

4. frontmatter 字段¶

---
name: code-review       # 必填
description: ...        # 必填
allowed-tools: Bash,Read  # 可选
model: sonnet            # 可选
---

4 字段。

4.1 name¶

唯一 ID。/name 触发。

4.2 description¶

关键字段 —— 决定什么时候自动触发（LLM 看到 description 后决定）。

4.3 allowed-tools¶

白名单。skill 可用工具。

4.4 model¶

指定模型。

5. 高级特性¶

5.1 $ARGUMENTS¶

Search: $ARGUMENTS

全部参数。

5.2 !bash¶

Run:
!bash
npm test

bash 代码块。

5.3 @file¶

Read @README.md

文件引用。

6. 5 个实战 Skill¶

6.1 code-review¶

---
name: code-review
description: When user asks for code review
---

# Code Review

Output:
- Issue (file:line)
- Severity (critical/medium/low)
- Fix suggestion

review。

6.2 test-gen¶

---
name: test-gen
description: When user asks to write tests
---

# Test Generator

1. Read source
2. Identify exports
3. For each: happy / edge / error tests
4. Use project's test framework

test。

6.3 refactor¶

---
name: refactor
description: When user asks to refactor
allowed-tools: Read, Edit
---

# Refactor

1. Read file
2. Identify smells
3. Suggest 3 refactorings
4. Apply one at a time

refactor。

6.4 commit-msg¶

---
name: commit-msg
description: When user runs /commit
allowed-tools: Bash
---

# Commit Message

1. git status / diff
2. Generate:
   - type (docs/feat/fix)
   - subject (50 chars)
   - body
3. NO Co-Authored-By Claude

commit。

6.5 explain¶

---
name: explain
description: When user asks to explain code
---

# Explain

For the given code:
1. What it does
2. Why it exists
3. How it works (line by line)
4. Edge cases

explain。

7. 3 层 Skill 分发¶

7.1 个人级¶

~/.claude/skills/

个人。

7.2 项目级¶

.claude/skills/

项目。

7.3 Plugin 内¶

<plugin>/skills/

Plugin。

8. 触发机制¶

8.1 显式¶

> /code-review

显式。

8.2 隐式（描述匹配）¶

> Can you review this code?
# Claude 看到 description "When user asks for code review"
# 自动触发

隐式。

8.3 优先级¶

显式 > 隐式
项目级 > 个人级
Plugin > 内置

3 优先级。

9. 5 个最佳实践¶

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

5 条。

10. 5 个常见错误¶

10.1 描述模糊¶

description: ...   # 太宽

模糊。

10.2 指令太多¶

# 100 行指令

太复杂。

10.3 依赖外部¶

# 假设有特定工具

强依赖。

10.4 没测试¶

# 写完不测

不测。

10.5 太频繁¶

description: ...   # 触发太频繁

太频繁。

11. 5 个调试¶

11.1 不触发¶

检查路径
重启
看 description

11.2 触发但无效¶

加详细指令
看输出

11.3 触发太频繁¶

description 更具体
加 negative example

11.4 错误¶

检查 frontmatter
简化指令

11.5 性能¶

简化 skill
缓存

12. Skill vs Command vs Plugin¶

维度	Skill	Command	Plugin
复杂度	简单	简单	复杂
触发	自动 / 显式	显式	显式
资源	1 个	1 个	5 个
分发	个人	个人	团队

何时用。

13. 完整示例¶

---
name: refactor
description: When user asks to refactor code
allowed-tools: Read, Grep, Glob, Edit
model: sonnet
---

# Refactor

## Steps

1. **Read** the file
2. **Analyze**:
   - Long functions (> 50 lines)
   - Deep nesting (> 3)
   - Duplicate code
   - Magic numbers
3. **Suggest** 3 refactorings
4. **Apply** one at a time
5. **Test** after each

## Output Format

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

完整。

14. 总结¶

Skill = 最简的扩展方式。

核心： - 2 种格式 - 4 字段 frontmatter - 3 变量（$ARGUMENTS / !bash / @file） - 3 层分发 - 隐式触发（描述匹配）

下一步： - 看 tutorials/build-skill.md - 写第一个 skill - 触发测试