Claude Code Skills 完全指南 Claude Code Skills 完全指南目录 Skills 是

Claude Code Skills 完全指南

面向有 Claude Code 基础的开发者，系统介绍 Skills 的概念、用法与进阶技巧。

1. Skills 是什么

Skill 是一个写给 Claude 看的"能力说明书"——创建一个带 SKILL.md 的目录，Claude 就把它加入工具箱。

两种触发方式：

自动触发：Claude 根据 description 字段判断当前对话是否相关，相关则自动加载
手动触发：你直接输入 /skill-name 主动调用

用户说："how does this work?"
  → Claude 读取所有 skill 的 description
  → 发现 explain-code 的描述匹配
  → 自动加载并按 skill 指令回答

2. Skills vs Commands

Skills 是 Commands 的超集，两者已官方合并：

.claude/commands/deploy.md          ← 旧格式，仍然有效
.claude/skills/deploy/SKILL.md      ← 新格式，功能更强

两种写法都创建 /deploy，效果完全相同。

特性	commands/ 旧格式	skills/ 新格式
创建 slash command	✅	✅
自动触发（Claude 判断）	❌	✅
支持子目录放支持文件	❌	✅
frontmatter 控制调用权限	部分	✅ 完整支持
在 Sub Agent 中运行	❌	✅ `context: fork`

建议：新写的统一用 skills/ 格式，旧的 commands/ 文件不需要迁移。

3. 快速上手

3.1 创建第一个 Skill

第一步：建目录

mkdir -p ~/.claude/skills/explain-code

第二步：写 SKILL.md

~/.claude/skills/explain-code/SKILL.md

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when
             explaining how code works, or when the user asks "how does
             this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Keep explanations conversational.

第三步：测试

# 方式一：让 Claude 自动触发
How does this code work?

# 方式二：手动调用
/explain-code src/auth/login.ts

3.2 目录结构

每个 skill 是一个目录，SKILL.md 是唯一必须的文件：

my-skill/
├── SKILL.md           # 必须，skill 入口
├── reference.md       # 可选：详细参考文档
├── examples/
│   └── sample.md      # 可选：示例
└── scripts/
    └── helper.py      # 可选：可执行脚本

文件名固定是 SKILL.md，不能改。Skill 的名称由目录名决定（也可在 frontmatter 的 name 字段覆盖）。

4. 存放位置与优先级

层级	路径	作用范围
企业级	管理员统一配置	组织所有用户
个人级	`~/.claude/skills/<name>/`	你的所有项目
项目级	`.claude/skills/<name>/`	当前项目，可提交 Git
插件级	`<plugin>/skills/<name>/`	插件启用的项目

优先级：企业 > 个人 > 项目 > 插件

同名 skill 高优先级覆盖低优先级。插件 skill 使用 plugin-name:skill-name 命名空间，不会冲突。

Monorepo 支持：编辑 packages/frontend/ 下的文件时，Claude Code 自动发现 packages/frontend/.claude/skills/ 中的 skill。

5. Frontmatter 完整参考

---
# ── 基础 ──────────────────────────────────────
name: my-skill                    # 可选，省略则用目录名。仅小写字母、数字、连字符，最长64字符
description: 一句话描述            # 强烈推荐。Claude 用此判断何时自动加载。超过250字符会被截断，关键词前置

# ── 调用控制 ──────────────────────────────────
disable-model-invocation: true    # 禁止 Claude 自动调用，只能用户手动 /name
user-invocable: false             # 不出现在 / 菜单，只有 Claude 能自动调用
argument-hint: "[file] [format]"  # 命令补全时显示的参数提示

# ── 执行环境 ──────────────────────────────────
allowed-tools: Read Grep Glob     # 限制可用工具，空格分隔
model: claude-opus-4-6            # 指定模型
effort: low                       # 思考力度：low / medium / high / max（max 仅 Opus 4.6）
context: fork                     # 在独立 Sub Agent 中运行（隔离上下文）
agent: Explore                    # 配合 context:fork，指定 Agent 类型

# ── 作用范围 ──────────────────────────────────
paths: "src/**/*.tsx"             # 只在匹配文件路径时自动激活，逗号分隔多个 glob

# ── 其他 ──────────────────────────────────────
shell: bash                       # 内联 shell 命令用的 shell，bash 或 powershell
---

调用控制对比

frontmatter	你能调用	Claude 能自动调用	description 进入上下文
（默认）	✅	✅	✅
`disable-model-invocation: true`	✅	❌	❌
`user-invocable: false`	❌	✅	✅

6. 控制触发方式

只允许手动触发（有副作用的操作）

部署、发消息、提交代码——你不希望 Claude 自己决定什么时候执行：

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true   # 防止 Claude 自动触发
---

Deploy $ARGUMENTS to production:
1. Run the test suite
2. Build the application
3. Push to the deployment target

只允许 Claude 自动加载（背景知识）

项目约定、遗留系统说明——不是用户要执行的操作，是 Claude 需要知道的上下文：

---
name: legacy-system-context
description: Context about our legacy payment system architecture
user-invocable: false   # 不出现在 / 菜单
---

Our legacy payment system was built in 2015 using...

传递参数

用 $ARGUMENTS 接收参数：

---
name: fix-issue
description: Fix a GitHub issue by number
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

/fix-issue 123
# Claude 收到："Fix GitHub issue 123 following our coding standards."

多个参数用 $ARGUMENTS[N] 或简写 $N：

---
name: migrate-component
---

Migrate the $0 component from $1 to $2.

/migrate-component SearchBar React Vue

7. 进阶用法

7.1 支持文件：拆分大型 Skill

SKILL.md 建议控制在 500 行以内，详细内容放到独立文件，按需加载：

my-api-skill/
├── SKILL.md          # 概述 + 导航，告诉 Claude 各文件的用途
├── endpoints.md      # 完整 API 文档（需要时才加载）
├── examples.md       # 使用示例
└── scripts/
    └── validate.py   # 验证脚本

在 SKILL.md 中引用：

## 补充资料

- 完整 API 文档见 [endpoints.md](endpoints.md)
- 使用示例见 [examples.md](examples.md)

7.2 动态注入上下文（`!` 语法）

用 !`command` 在 skill 运行前执行 shell 命令，将输出插入 prompt：

---
name: pr-summary
description: Summarize a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Task
Summarize this pull request, focusing on what changed and why.

执行顺序：shell 命令先执行 → 输出替换占位符 → Claude 收到完整渲染后的 prompt。

这是预处理，不是 Claude 执行命令——Claude 只看到最终结果。

7.3 在 Sub Agent 中运行（`context: fork`）

skill 在独立上下文中运行，不共享主对话历史：

---
name: deep-research
description: Research a topic thoroughly using codebase exploration
context: fork         # 独立 Sub Agent
agent: Explore        # 只读工具，适合代码探索
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

可用的内置 Agent 类型：Explore（只读探索）、Plan（规划）、general-purpose（通用），以及你在 .claude/agents/ 里自定义的 Agent。

7.4 路径限定自动触发（`paths`）

只在操作特定文件时自动激活：

---
name: react-conventions
description: React component conventions for this project
paths: "src/components/**/*.tsx, src/pages/**/*.tsx"
---

When writing React components in this project:
- Use functional components only
- Co-locate styles in .module.css files
...

7.5 开启深度思考

在 skill 内容任意位置加入 ultrathink 关键词，即可为该 skill 开启 extended thinking：

---
name: architecture-review
---

ultrathink

Review the architecture of $ARGUMENTS and identify potential issues...

8. 内置 Bundled Skills

Claude Code 自带以下 skill，无需安装，直接使用：

Skill	用途
`/batch <instruction>`	大规模并行代码变更，自动拆解任务、多 Agent 并行执行、各自开 PR
`/debug [description]`	开启 debug 日志，分析当前会话问题
`/loop [interval] <prompt>`	定时重复执行一个 prompt，适合轮询部署状态等
`/simplify [focus]`	并行启动 3 个 review Agent，找出代码质量问题并修复
`/claude-api`	加载 Claude API 参考文档（Python/TS/Go 等多语言）

9. 常见问题

Q: Skill 不自动触发？

检查 description 是否包含用户会自然说出的关键词
输入 /skills 确认 skill 是否被识别
直接 /skill-name 手动触发验证 skill 本身是否正常

Q: Skill 触发太频繁？

让 description 更具体，减少误匹配
加 disable-model-invocation: true 改为纯手动触发

Q: Description 被截断？

每条 description 最多显示 250 字符
把最关键的触发场景放在描述最前面

Q: skills/ 和 commands/ 需要迁移吗？

不需要，commands/ 文件继续有效
只有需要自动触发、支持文件、Sub Agent 等新特性时才值得迁移到 skills/ 格式

Q: 同事怎么共享 skill？

项目级：把 .claude/skills/ 提交到 Git，clone 即用
个人/团队：创建一个配置仓库，写 install.sh 脚本复制到 ~/.claude/skills/

Claude Code Skills 完全指南