创建你的第一个 Skill

这篇教程将引导你完成创建一个 Skill 的完整流程。我们将创建一个简单的 “代码审查检查清单” Skill，它帮助 Claude 在代码审查时遵循一致的检查项。

This tutorial walks you through creating a complete Skill. We’ll build a simple “Code Review Checklist” Skill that helps Claude follow consistent checklist items during code reviews.

Step 1: 创建项目结构

首先创建 Skill 的目录结构。最小结构只需一个 SKILL.md 文件。

First, create the Skill directory structure. The minimal structure needs only a SKILL.md file.

mkdir code-review-checklist
cd code-review-checklist
touch SKILL.md

Step 2: 编写 SKILL.md

SKILL.md 是 Skill 的核心。它包含 YAML frontmatter（元数据）和 Markdown body（指令）。

SKILL.md is the core of the Skill. It contains YAML frontmatter (metadata) and Markdown body (instructions).

SKILL.md — 完整的 Skill 文件

1 --- 2 name: code-review-checklist 3 description: Apply a standardized code review checklist when 4 tableOfContents: false reviewing pull requests, diffs, or code changes. Use this skill 5 whenever the user asks for a code review, PR review, mentions 6 reviewing code, or shares a diff for feedback. 7 --- 8 9 # Code Review Checklist 10 11 ## Overview 12 13 Use this checklist when reviewing any code change. The goal is 14 consistent, thorough reviews that catch common issues. 15 16 ## Checklist 17 18 ### Correctness 19 - [ ] Does the code handle edge cases (null, empty, error states)? 20 - [ ] Are there potential race conditions or concurrency issues? 21 - [ ] Are error messages clear and actionable? 22 23 ### Performance 24 - [ ] Are there unnecessary database queries or API calls? 25 - [ ] Could this code benefit from caching? 26 - [ ] Is the algorithmic complexity appropriate? 27 28 ### Security 29 - [ ] Is user input validated and sanitized? 30 - [ ] Are secrets or credentials hard-coded? 31 - [ ] Are permissions checked correctly? 32 33 ### Maintainability 34 - [ ] Are function and variable names clear? 35 - [ ] Is the code DRY (Don't Repeat Yourself)? 36 - [ ] Are there adequate comments for non-obvious logic? 37 38 ## Review Output Format 39 40 When reviewing, structure your feedback as: 41 42 1. **Summary** — 2-3 sentence overall assessment 43 2. **Critical Issues** — Must-fix before merge 44 3. **Suggestions** — Nice-to-have improvements 45 4. **Questions** — Items needing author clarification

代码解读

L1 YAML frontmatter 开始。用 --- 分隔。 L2 name: 唯一标识符。小写+连字符。 L3 description: 这是最重要的字段。注意它包含：功能描述 + 触发场景 + 关键词（code review, PR review, reviewing code, diff feedback）。宁可 over-trigger。 L10 Overview 部分：快速说明 Skill 的目的。 L14 Checklist 是核心内容——结构化为 4 个维度的检查项。使用 Markdown checkbox 格式。 L34 Review Output Format: 定义输出结构。这确保所有代码审查的输出格式一致。

Step 3: 添加参考文档（可选）

如果你的 Skill 需要参考信息（如公司编码规范、API 文档等），可以放在 references/ 目录中。

If your Skill needs reference information (e.g., company coding standards, API docs), place them in the references/ directory.

mkdir references
cat > references/coding-standards.md << 'EOF'
# Company Coding Standards

- Use 2-space indentation
- Prefer async/await over raw promises
- Maximum function length: 50 lines
- Required test coverage: 80%
EOF

Step 4: 测试你的 Skill

在 Claude Code 中注册并测试你的 Skill：

# Register your skill in Claude Code
# Add to .claude/settings.json or use /plugin
# Then test it:
echo "Review this PR: [paste diff]" | claude

验证 Claude 是否：

正确触发了你的 Skill（检查是否按 checklist 格式输出）
覆盖了所有检查维度
输出格式符合 Review Output Format 定义

Verify Claude:

Correctly triggered your Skill (check if output follows checklist format)
Covered all review dimensions
Output format matches Review Output Format definition

Step 5: 迭代优化

基于测试结果迭代改进：

如果 Skill 没有被触发 → 增强 description 字段
如果遗漏了某个检查维度的 → 补充 checklist 条目
如果输出格式不稳定 → 在 “Review Output Format” 中增加更具体的指令

参考 skill-creator 学习如何使用量化评估体系来系统性地优化你的 Skill。

Iterate based on test results:

If Skill is not triggered → strengthen the description field
If a review dimension is missed → add checklist items
If output format is inconsistent → add more specific instructions in “Review Output Format”

See skill-creator to learn how to use a quantitative evaluation system to systematically optimize your Skill.