Claude Code Skills 编写指南：从入门到高级 (2026)

Claude Code的Skills功能常让开发者感到困惑：它本质上是基于SKILL.md文件的模块化能力扩展机制。只需编写一个包含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的存储位置

同名Skills以高优先级覆盖低优先级：企业 > 个人 > 项目 > 插件。插件Skills使用plugin-name:skill-name命名空间，避免与其他层级冲突。

创建第一个Skill的完整流程

第一步：创建目录

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

第二步：编写SKILL.md

每个Skill必须包含一个SKILL.md文件，由两部分构成：

1. YAML frontmatter（---包裹）：定义Claude何时使用、如何调用
2. 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: command
          command: "./validate.sh"
---

三种调用控制组合：

文件目录结构详解

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: 的形式追加到末尾。

位置参数：$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

动态上下文注入技巧

利用 !`` 语法，可在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.

执行顺序如下：

1. !`gh pr diff` 等命令立即执行
2. 命令输出替换占位符
3. 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类型一览：

也可自定义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:

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 Skills

Claude Code预置了若干Skills，无需配置即可直接使用：

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内的脚本文件