Claude Code Skills 技能系统完全指南

为 Claude Code 创建可复用的技能模块，一次编写，处处使用。

什么是 Skill？

Skill 是 Claude Code 的可复用提示词模块。与 Agent 不同，Skill 不是独立的角色，而是一段可被调用的指令，类似于"函数"——定义一次，随时调用。

Skill 文件存放位置

.claude/skills/               # 项目级 — ⚠️ 必须是目录格式
├── lint-fix/
│   └── SKILL.md
├── deploy/
│   ├── SKILL.md
│   └── scripts/
│       └── deploy.sh
└── generate-api/
└── SKILL.md

~/.claude/skills/              # 用户级（全局可用）
├── my-template/
│   └── SKILL.md
└── code-review/
└── SKILL.md

重要：/skills/ 目录只支持目录格式（skill-name/SKILL.md），不支持单个 .md 文件。

创建 Skill

基本结构

创建 .claude/skills/lint-fix/SKILL.md：

---
description: 自动修复项目中的 lint 错误
---

请执行以下步骤修复 lint 错误：

1. 运行 `npm run lint` 查看当前错误
2. 逐个文件修复所有 lint 错误
3. 再次运行 `npm run lint` 确认全部修复
4. 总结修复了哪些问题

调用方式：在 Claude Code 中输入 /lint-fix

Frontmatter 参数详解

---
name: 显示名称                    # 可选：替代目录名作为显示名
description: Skill 描述           # 推荐：描述此 Skill 的用途
when_to_use: 当用户需要...时使用  # 可选：何时应该自动使用此 Skill
model: claude-sonnet-4-6          # 可选：指定模型
effort: medium                    # 可选：思考努力级别
user-invocable: true              # 可选：是否可通过 /command 调用（默认 true）
allowed-tools:                    # 可选：Skill 内允许使用的工具
  - Bash
  - Read
  - Edit
arguments: [file, type]           # 可选：参数名列表
argument-hint: "<file> [type]"    # 可选：参数提示
context: fork                     # 可选：在 fork 的上下文中执行
agent: test-writer                # 可选：指定执行此 Skill 的 Agent
paths:                            # 可选：仅在操作匹配路径的文件时激活
  - "src/components/**"
  - "*.tsx"
shell: bash                       # 可选：内联 shell 命令使用的 shell
hooks:                            # 可选：Skill 专属的钩子
  PostToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "echo done"
---

实战示例

示例 1：带参数的 Skill

---
description: 为指定组件生成单元测试
arguments: [component]
argument-hint: "<component-name>"
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
---

为组件 $ARGUMENTS 生成完整的单元测试。

步骤

1. 先读取 $ARGUMENTS 的源代码，理解其功能
2. 检查项目中已有的测试文件格式和框架
3. 创建对应的测试文件
4. 运行测试确保通过

测试要求

• 覆盖所有公开方法
• 包含边界情况测试
• 包含错误处理测试
• 使用 mock 隔离外部依赖

调用：/generate-test UserProfile

示例 2：带内联 Shell 命令的 Skill

---
description: 分析项目的代码复杂度
allowed-tools:
  - Read
  - Bash
---

项目代码分析

先获取项目信息：

!wc -l $(find src -name '*.ts' -o -name '*.tsx') | tail -1

!git log --oneline -10

基于以上信息，分析：

1. 代码总量和分布
2. 最近的活跃文件
3. 代码复杂度评估
4. 潜在的重构建议

! 语法：以 ! 开头的代码块会在 Skill 执行时先运行 shell 命令，将输出注入到提示词中。

示例 3：使用 ${CLAUDE_SKILL_DIR} 的 Skill

---
description: 使用自定义脚本检查代码质量
allowed-tools:
  - Bash
  - Read
---

运行代码质量检查：

!bash ${CLAUDE_SKILL_DIR}/scripts/quality-check.sh

基于上述检查结果，给出改进建议。

Skill 目录结构：

.claude/skills/quality-check/
├── SKILL.md
└── scripts/
    └── quality-check.sh

${CLAUDE_SKILL_DIR} 会被替换为 Skill 所在的目录路径，方便引用附带的脚本和资源。

示例 4：条件激活的 Skill

---
description: React 组件开发规范检查
user-invocable: false
when_to_use: 当用户创建或修改 React 组件时自动检查规范
paths:
  - "src/components/**"
  - "**/*.tsx"
---

检查当前操作的 React 组件是否符合以下规范：

1. 是否使用函数组件而非 class 组件
2. Props 是否有 TypeScript 类型定义
3. 是否正确使用 React Hooks
4. 组件是否有适当的 key 属性
5. 是否避免了不必要的 re-render

关键参数：

• user-invocable: false — 不能通过 /command 手动调用
• paths — 只在操作匹配路径的文件时自动激活
• when_to_use — 告诉 Claude 何时应该使用此 Skill

示例 5：带多个参数的 Skill

---
description: 从模板创建新的 API 端点
arguments: [method, path]
argument-hint: "<GET|POST|PUT|DELETE> <api-path>"
allowed-tools:
  - Read
  - Write
  - Edit
---

创建一个新的 API 端点：

• HTTP 方法：$1
• 路由路径：$2

生成规范

1. 在 src/routes/ 下创建路由文件
2. 在 src/controllers/ 下创建控制器
3. 在 src/validators/ 下创建请求验证器
4. 更新 src/routes/index.ts 的路由注册
5. 创建对应的测试文件

调用：/create-endpoint POST /api/users

Skill vs Commands（旧版）

/commands/ 目录是旧版的自定义命令系统，仍然兼容但建议迁移到 /skills/：

其他可用变量

注意事项

1. 目录名就是命令名：skills/deploy/ → /deploy
2. 嵌套目录用冒号分隔：skills/infra/deploy/ → /infra:deploy
3. SKILL.md 文件名大小写不敏感
4. 同名 Skill 去重：通过 realpath 去重，避免符号链接导致重复
5. MCP 远程 Skill 的 shell 命令会被禁用（安全考虑）