Claude Code Skill 详解
深入理解 Skill 的设计理念、规范结构与实际应用
Skill 是 Claude Code 中的可复用知识模块， 它封装了特定领域的最佳实践、规范和工作流程。Skill 不能被用户直接调用，而是作为 Command 和 Agent 的"能力组件"被引用。
核心特征
📦
模块化
每个 Skill 专注于单一领域，如 TDD、安全审查、代码规范等
🔄
可复用
一个 Skill 可被多个 Command/Agent 引用，避免重复定义
📋
声明式
通过 Markdown 定义，包含 frontmatter 元数据和详细指导
🎯
上下文感知
通过 description 字段让 Claude 理解何时该激活此 Skill
Skill 解决的问题
- 知识固化 - 将团队积累的最佳实践转化为可执行指令
- 一致性保障 - 确保所有成员遵循相同的规范和流程
- 降低认知负担 - 无需记忆复杂流程，Skill 会自动指导执行
- 持续改进 - 更新 Skill 后所有引用它的组件自动获得改进
Claude Code 的配置体系由三大核心组件构成，它们各司其职又相互协作：
📁
Command (命令)
存放位置
commands/*.md调用方式
/commit, /plan用途
用户可直接调用的快捷指令，定义完整的任务流程
📦
Skill (技能)
存放位置
skills/*/SKILL.md调用方式
不可直接调用用途
可复用的知识模块，被 Command/Agent 引用以获得特定能力
🤖
Agent (代理)
存放位置
agents/*.md调用方式
由 Task 工具调用用途
专门化的子代理，执行特定类型的复杂任务（如代码审查、TDD）
💡 关系类比
Command = 餐厅菜单上的菜品（顾客可以直接点）
Skill = 后厨的标准食谱（定义如何制作）
Agent = 专业厨师（专注于某一类菜品）
协作关系
/commit
→ 引用 →git-conventions
tdd-guide agent
→ 引用 →tdd-workflow
Skill 文件采用 Markdown + YAML Frontmatter 格式，结构清晰且易于维护：
skills/tdd-workflow/SKILL.md
---
name: tdd-workflow
description: Use this skill when writing new features,
fixing bugs, or refactoring code. Enforces test-driven
development with 80%+ coverage.
---
# Test-Driven Development Workflow
This skill ensures all code follows TDD principles.
## When to Activate
- Writing new features or functionality
- Fixing bugs or issues
- Refactoring existing code
## Core Principles
### 1. Tests BEFORE Code
ALWAYS write tests first, then implement code.
### 2. Coverage Requirements
- Minimum 80% coverage
- All edge cases covered
- Error scenarios tested
## TDD Workflow Steps
### Step 1: Write Failing Tests
```typescript
describe('UserService', () => {
it('creates user with valid data', async () => {
// Test implementation
})
})
```
### Step 2: Implement Code
Write minimal code to make tests pass.
### Step 3: Refactor
Improve code quality while keeping tests green.文件结构解析
1. Frontmatter (必需)
nameSkill 的唯一标识符，用于引用description详细描述，帮助 Claude 判断何时激活此 Skill2. When to Activate (推荐)
列出触发此 Skill 的场景，让 Claude 明确知道什么时候该应用这些规则
3. Core Principles (核心)
定义核心原则和规则，这是 Skill 的主要价值所在
4. Workflow Steps (可选)
具体的执行步骤，包含代码示例和最佳实践
📝 description 字段的重要性
description 是 Claude 决定是否激活 Skill 的关键。 应该清晰描述：什么情况下使用、能解决什么问题、提供什么能力。 写得越具体，Claude 的判断就越准确。
Skill 支持两种作用域：全局级别（用户目录）和项目级别：
🌐全局 Skills（所有项目共享）
~/.claude/
├── skills/
│ ├── git-conventions/
│ │ └── SKILL.md
│ ├── coding-standards/
│ │ └── SKILL.md
│ └── security-review/
│ └── SKILL.md
├── commands/
│ └── commit.md
└── agents/
└── reviewer.md📁项目 Skills（仅当前项目）
your-project/
├── .claude/
│ ├── skills/
│ │ ├── api-design/
│ │ │ └── SKILL.md
│ │ └── db-migrations/
│ │ └── SKILL.md
│ └── commands/
│ └── deploy.md
├── src/
└── package.json⚠️ 优先级规则
当全局和项目存在同名 Skill 时，项目级别优先。 这允许项目覆盖全局配置以满足特定需求。
命名约定
skills/skill-name/SKILL.md→标准格式（推荐）skills/skill-name/skill.md→小写也可以以下是几个常用的 Skill 示例，展示不同场景下的最佳实践：
示例 1：coding-standards（代码规范）
---
name: coding-standards
description: Universal coding standards for TypeScript,
React, and Node.js. Apply when writing or reviewing code.
---
# Coding Standards
## Variable Naming
- Use camelCase for variables: `userName`
- Use PascalCase for components: `UserProfile`
- Use UPPER_SNAKE_CASE for constants: `MAX_RETRIES`
## TypeScript Rules
- NO `any` type - always define proper types
- Use interfaces for object shapes
- Enable strict mode
## React Patterns
- Functional components only
- Custom hooks for reusable logic
- Props interface for every component示例 2：security-review（安全审查）
---
name: security-review
description: Security vulnerability detection. Use when
reviewing code that handles user input, authentication,
API endpoints, or sensitive data.
---
# Security Review Checklist
## Critical Checks
- [ ] No hardcoded secrets or API keys
- [ ] Input validation on all user data
- [ ] SQL injection prevention (parameterized queries)
- [ ] XSS prevention (escape output)
## Authentication
- [ ] Passwords properly hashed (bcrypt/argon2)
- [ ] JWT tokens have expiration
- [ ] Session management secure
## OWASP Top 10
- Injection, Broken Auth, XSS, CSRF, etc.示例 3：backend-patterns（后端模式）
---
name: backend-patterns
description: Backend architecture patterns, API design,
and database optimization for Node.js and Next.js.
---
# Backend Patterns
## API Response Format
```typescript
interface ApiResponse<T> {
success: boolean
data?: T
error?: string
}
```
## Error Handling
- Use custom ApiError class
- Centralized error handler
- Proper HTTP status codes
## Database
- Repository pattern for data access
- Avoid N+1 queries
- Use transactions for multi-step operations方式一：自动激活
Claude 会根据 description 自动判断是否需要激活某个 Skill。 当你的请求匹配 Skill 的描述时，Claude 会自动应用其中的规则。
用户请求：
"帮我写一个用户注册的 API"
Claude 自动激活：
backend-patternssecurity-reviewcoding-standards
方式二：通过 Command 引用
Command 可以显式声明依赖的 Skill，确保执行时加载相关规则：
commands/commit.md
---
description: Generate and commit with conventional format
---
# Commit Command
Uses: @skill:git-conventions
## Workflow
1. Run git status and git diff
2. Analyze changes
3. Generate commit message per git-conventions
4. Execute git commit执行流程图解
1
用户输入
/commit2
加载
commands/commit.md3
解析并加载
skills/git-conventions/SKILL.md4
执行 workflow，应用 Skill 中的规则
✓
输出符合规范的 commit message
推荐做法
- ✓精确的 description - 明确说明激活场景
- ✓提供代码示例 - 用示例展示期望的格式
- ✓包含正反例 - 用 ✅/❌ 对比好坏实践
- ✓保持聚焦 - 每个 Skill 专注一个领域
- ✓可操作指令 - 使用祈使句而非描述句
避免做法
- ✗模糊的描述 - 如 "通用编程技能"
- ✗过于庞大 - 一个 Skill 包含所有内容
- ✗重复定义 - 多个 Skill 有重叠内容
- ✗缺少示例 - 只有抽象规则没有具体示例
💡 设计原则
好的 Skill 应该像一位经验丰富的导师：不仅告诉你"该做什么"， 还要说明"为什么这样做"，并通过具体示例展示"怎么做"。 Claude 读取 Skill 后应该能立即理解并正确应用这些规则。