Claude Code Skills 是一种通过 `SKILL.md` 文件扩展 Claude 能力的模块化机制，开发者编写一个包含 YAML frontmatter 和 Markdown 指令的文件，Claude 就能将其作为工具调用——直接用 `/skill-name` 触发，或在对话中自动识别并激活。Skills 遵循 [Agent Skills 开放标准（agentskills.io）](https://agentskills.io)，可跨多种 AI 工具共享。Claude Code Skills 是一种通过 SKILL.md 文件扩展 Claude 能力的模块化机制，开发者编写一个包含 YAML frontmatter 和 Markdown 指令的文件，Claude 就能将其作为工具调用——直接用 /skill-name 触发，或在对话中自动识别并激活。Skills 遵循 Agent Skills 开放标准（agentskills.io），可跨多种 AI 工具共享。
Skills 是什么，和 Commands 有什么区别？
Skills 是 Commands 的超集。 两者在功能上等价——.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都会创建 /deploy 命令，行为相同。现有 .claude/commands/ 文件无需迁移，继续有效。
Skills 在 Commands 基础上额外支持：
- 目录结构：可附带模板、脚本、示例等支持文件
- Frontmatter 控制：指定调用权限、工具限制、模型选择
- Subagent 执行：通过
context: fork在独立上下文中运行 - 动态上下文注入：用
!`command`在运行前预填充实时数据 - 参数占位符：
$ARGUMENTS、$0、$1等位置参数
Skills 存放位置
| 位置 | 路径 | 作用范围 |
|---|---|---|
| 企业级 | 托管配置（managed settings） | 组织内所有用户 |
| 个人级 | ~/.claude/skills/<skill-name>/SKILL.md |
你的所有项目 |
| 项目级 | .claude/skills/<skill-name>/SKILL.md |
当前项目 |
| 插件级 | <plugin>/skills/<skill-name>/SKILL.md |
插件启用范围 |
同名 Skills 以高优先级覆盖低优先级：企业 > 个人 > 项目 > 插件。插件 Skills 使用 plugin-name:skill-name 命名空间，不会与其他层级冲突。
创建第一个 Skill：分步教程
步骤一：创建目录
mkdir -p ~/.claude/skills/explain-code
步骤二：编写 SKILL.md
每个 Skill 必须有一个 SKILL.md 文件，由两部分组成：
- YAML frontmatter（
---之间）：告知 Claude 何时使用、如何调用 - Markdown 正文：Claude 执行时遵循的指令
---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, 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, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?
步骤三：测试
两种触发方式：
# 方式一：让 Claude 自动识别
How does this code work?# 方式二：直接调用
/explain-code src/auth/login.ts
Frontmatter 完整字段参考
---
name: my-skill # 目录名即默认名，可省略
description: "..." # 推荐填写，Claude 据此决定是否自动加载
argument-hint: "[filename]" # /slash 命令补全提示
disable-model-invocation: true # true = 只有用户能触发，Claude 不自动调用
user-invocable: false # false = 只有 Claude 能调用，不出现在 / 菜单
allowed-tools: Read, Grep # 该 Skill 激活时允许使用的工具（无需逐次确认）
model: sonnet # 可选: sonnet / opus / haiku / 完整模型ID
effort: high # 思考力度: low / medium / high / max（仅 Opus 4.6）
context: fork # fork = 在独立 subagent 上下文中运行
agent: Explore # context: fork 时指定 agent 类型
hooks: # Skill 生命周期钩子PreToolUse:- matcher: "Bash"hooks:- type: commandcommand: "./validate.sh"
---
三种调用控制组合：
| frontmatter 配置 | 用户可触发 | Claude 自动触发 | 描述是否加载到上下文 |
|---|---|---|---|
| 默认（无设置） | ✓ | ✓ | ✓ |
disable-model-invocation: true |
✓ | ✗ | ✗ |
user-invocable: false |
✗ | ✓ | ✓ |
文件目录结构
Skills 目录支持附带支持文件，SKILL.md 作为入口并引用它们：
my-skill/
├── SKILL.md # 主指令（必须）
├── template.md # Claude 填写的模板
├── examples/
│ └── sample.md # 示例输出，展示期望格式
└── scripts/└── validate.sh # Claude 可执行的脚本
在 SKILL.md 中引用：
## Additional resources
- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)
建议：
SKILL.md保持在 500 行以内，细节移入支持文件按需加载。
参数传递
基础用法：$ARGUMENTS
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---Fix GitHub issue $ARGUMENTS following our coding standards.1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit
运行 /fix-issue 123 时，$ARGUMENTS 被替换为 123。
若 Skill 内容没有 $ARGUMENTS，参数会以 ARGUMENTS: <value> 形式附加到末尾。
位置参数：$0、$1、$ARGUMENTS[N]
---
name: migrate-component
description: Migrate a component from one framework to another
---Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.
运行 /migrate-component SearchBar React Vue 时：
$0→SearchBar$1→React$2→Vue
动态上下文注入
使用 !`<command>` 语法，在 Skill 内容发送给 Claude 之前预执行 shell 命令，将输出内嵌到提示词：
---
name: pr-summary
description: Summarize changes in 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`## Your task
Summarize this pull request concisely, highlighting key changes and potential risks.
执行顺序：
!`gh pr diff`等命令立即执行- 命令输出替换占位符
- Claude 接收到已填充真实数据的完整提示词
这是预处理，不是 Claude 执行的命令。Claude 只看到最终渲染结果。
在 Subagent 中运行 Skill
添加 context: fork 使 Skill 在独立隔离的上下文中运行，不携带主对话历史：
---
name: deep-research
description: Research a topic thoroughly
context: fork
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 类型：
| Agent | 模型 | 工具 | 适用场景 |
|---|---|---|---|
Explore |
Haiku（快速） | 只读工具 | 代码库搜索与分析 |
Plan |
继承 | 只读工具 | 计划模式下的研究 |
general-purpose |
继承 | 全部工具 | 复杂多步骤任务 |
也可指定自定义 subagent：agent: my-custom-agent。
高级模式：生成可视化输出
Skills 可以打包脚本，生成交互式 HTML 可视化报告并在浏览器中打开：
---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo or understanding project structure.
allowed-tools: Bash(python *)
---Run the visualization script from your project root:```bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .
This creates codebase-map.html in the current directory and opens it in your default browser.
将 Python 脚本放在 `scripts/visualize.py`，Skill 负责调度，脚本负责生成。这一模式同样适用于依赖关系图、测试覆盖率报告、API 文档等场景。---## 内置 Bundled SkillsClaude Code 自带以下 Skills，无需任何配置即可使用：| Skill | 功能 |
|-------|------|
| `/batch <instruction>` | 并行大规模代码库修改，自动分解为 5-30 个独立子任务并行执行 |
| `/claude-api` | 加载 Claude API 参考资料，支持 Python/TypeScript/Go 等语言 |
| `/debug [description]` | 读取当前会话调试日志，分析问题 |
| `/loop [interval] <prompt>` | 按时间间隔重复运行提示词，适合监控部署或定时任务 |
| `/simplify [focus]` | 并行启动三个审查 agent，合并结果并修复代码质量问题 |---## Skills 上下文加载机制普通会话中：
- Skill 的 **description** 始终在上下文中（Claude 知道有哪些可用）
- Skill **完整内容**只在被调用时才加载若你有大量 Skills 导致 description 超出字符预算，可通过 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 环境变量覆盖默认限制（默认为上下文窗口的 2%，最小 16,000 字符）。运行 `/context` 可查看是否有 Skills 因超出预算被排除。---## 常见问题**Q：Skill 不触发怎么办？**
检查 `description` 是否包含用户自然表达中的关键词；运行"What skills are available?"确认 Skill 已加载；尝试用 `/skill-name` 直接调用。**Q：Skill 触发过于频繁怎么办？**
将 `description` 写得更具体，或设置 `disable-model-invocation: true` 改为仅手动触发。**Q：Skills 和 Subagents 如何配合使用？**
两者互补：在 Skill 中设置 `context: fork` 可让 Skill 在指定 agent 中运行；在 Subagent 定义中用 `skills` 字段可将 Skills 预加载为 subagent 的领域知识。本质上使用同一底层系统，方向相反。**Q：如何限制 Skill 只能用特定工具？**
用 `allowed-tools` 字段指定白名单，例如 `allowed-tools: Read, Grep, Glob`，Skill 激活期间无需逐次授权，同时阻止使用其他工具。**Q：能否在 Skill 中读取当前 Session ID 或 Skill 目录路径？**
可以。使用内置变量：
- `${CLAUDE_SESSION_ID}` — 当前 session ID，适合日志和文件命名
- `${CLAUDE_SKILL_DIR}` — Skill 所在目录的绝对路径，适合引用 Skill 内的脚本文件---## 延伸资源- Skills 官方文档：[code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills)
- Subagents 文档：[code.claude.com/docs/en/sub-agents](https://code.claude.com/docs/en/sub-agents)
- Agent Skills 开放标准：[agentskills.io](https://agentskills.io)
- Claude Code Skills 示例与技能包：[linskills.qiniu.com](https://linskills.qiniu.com)---*本文内容基于 Claude Code 官方文档（code.claude.com/docs，2026 年 3 月）整理。Skills 规范随版本持续迭代，建议以官方文档为准。*