Claude Code Skills 高阶用法：从配置到实战的 8 个特性详解

很多人把 Skill 单纯地看作是一个“保存的 Prompt”，习惯在描述里写上一大段，正文里塞满工作手册。结果就是 Skills 越加越多，上下文先被撑爆了。

这篇指南不讲基础入门，只聚焦那些分散在官方文档各处、看完就能直接上手的硬核特性与实战技巧。

1. 目录结构不是只有 SKILL.md

一个 Skill 就是一个目录，SKILL.md 是主入口文件，但它并不是全部。

my-skill/
├── SKILL.md           # 必选：主指令文件
├── template.md        # 可选：供 Claude 填充的模板文件
├── examples/          # 可选：示例输出目录
│   └── sample.md
└── scripts/           # 可选：可执行脚本目录
    └── validate.sh

关键在于，SKILL.md 应该只放置导航说明和核心约束，详细的文档、示例和脚本应该拆分到对应的 supporting files 中。官方建议 SKILL.md 最好控制在 500 行以内，这对控制上下文长度至关重要。

2. Frontmatter 完整字段清单

官方文档列出了 9 个 Frontmatter 字段，但很多人在使用时并未用全。充分理解这些字段，是编写高效、安全 Skill 的第一步。

---
name: my-skill              # 技能名称（默认使用目录名）
description: 什么时候调用    # 必填！决定 Claude 何时自动加载该技能
argument-hint: [filename]   # 参数自动补全提示
disable-model-invocation: true  # 设为 true 时，只有用户能调用，Claude 不能自动触发
user-invocable: false       # 设为 false 时，只有 Claude 能调用，用户看不到此技能
allowed-tools: Read, Grep   # 限制此技能可用的工具
model: claude-sonnet-4-20250514  # 指定执行此技能时使用的模型
context: fork               # 在独立的子 agent 上下文中运行此技能
agent: Explore              # 指定子 agent 的类型
hooks:                      # 生命周期钩子
  on-invoke: ./hook.sh
---

高频应用场景：

• 有副作用的操作（如部署、发送消息） → 务必设置 disable-model-invocation: true
• 纯背景知识补充，无需用户手动调用 → 可以设置 user-invocable: false
• 只想让 Claude 在使用该技能时调用特定工具 → 利用 allowed-tools 进行限制

3. 字符串替换：让 Skill 接收参数

通过字符串替换，你的 Skill 可以从用户那里接收动态参数，变得更加灵活。

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

Fix GitHub issue $ARGUMENTS following our coding standards.

当用户运行 /fix-issue 123 时，$ARGUMENTS 会被自动替换成 123。

更灵活的变量用法：

变量	效果
$ARGUMENTS	替换为全部参数
$ARGUMENTS[0]	替换为第 1 个参数（0-based 索引）
$0, $1	简写形式，分别对应第1、第2个参数
${CLAUDE_SESSION_ID}	替换为当前会话 ID
${CLAUDE_SKILL_DIR}	替换为该 Skill 的目录路径

例如，执行 /migrate-component SearchBar React Vue 时：

• $0 = SearchBar
• $1 = React
• $2 = Vue

4. 动态上下文注入：这个特性 90% 的人没用过

使用 !`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`

## Your task
Summarize this pull request...

它的执行流程是：

1. 先执行三个反引号内的命令。
2. 用命令的真实输出替换掉占位符。
3. Claude 最终看到的是包含了实时数据（如 PR diff、评论）的完整 prompt。

这才是真正的“动态”——内容并非写死，而是在运行时根据实际情况获取的。如果你经常需要查阅官方文档来确认某些复杂特性的用法，这个技巧能帮你把动态查询的结果直接整合到工作流中。

5. context: fork 在子 agent 中运行

通过设置 context: fork，可以让 Skill 在一个独立的子 agent 上下文中执行。

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files
2. Read and analyze
3. Summarize with file references

添加 context: fork 后，效果如下：

• 创建一个独立、隔离的上下文环境。
• SKILL.md 中的内容将成为子 agent 的专属任务。
• 子 agent 的执行不会影响主会话的历史记录。
• 可以通过 agent 字段选择子 agent 的类型（Explore / Plan / general-purpose）。

适用场景： 后台深度研究、批量文件操作等长耗时任务，避免污染清晰的主会话流。

6. 权限控制：精细到每个 Skill

Claude Code 的权限系统允许你对 Skill 的调用进行精细控制。

# 在会话中只允许调用特定的 Skill
Skill(commit)
Skill(review-pr *)

# 在会话中禁止调用特定的 Skill
Skill(deploy *)

语法说明：Skill(name) 用于精确匹配，Skill(name *) 用于前缀匹配（通配符）。
结合前文提到的 disable-model-invocation: true 和 allowed-tools 字段，你可以为不同的项目或场景实现非常细粒度的安全与行为控制。

7. 作用域优先级

Skill 的存放位置决定了它的可用范围，了解这一点能帮你更好地组织和管理技能。

作用域	存放路径示例	影响范围
Enterprise（企业级）	由托管服务商配置	整个组织
Personal（个人级）	~/.claude/skills/	你所有的项目
Project（项目级）	.claude/skills/	仅当前项目
Plugin（插件级）	<plugin>/skills/	仅在启用该插件时

优先级顺序（从高到低）： Enterprise > Personal > Project > Plugin

插件中的 Skill 会使用 plugin-name:skill-name 这样的命名空间，因此不会与其他作用域的 Skill 发生冲突。

8. 5 个内置 Bundled Skills

Claude Code 自带 5 个官方的 Bundled Skills，很多用户并未充分利用它们。

Skill	用途与说明
/batch <instruction>	生产力利器。将一个指令拆分成 5-30 个并行子任务，每个任务在独立的 git worktree 中执行，适合大规模批量修改。
/claude-api	自动加载当前项目所用编程语言的 Anthropic API 参考文档。
/debug [description]	读取并分析当前会话的调试日志，帮助诊断问题。
/loop [interval] <prompt>	定时轮询执行某个任务，例如等待部署完成、监控构建状态等。
/simplify [focus]	启动三个并行的审查 agent，共同寻找代码中的问题并提供修复建议。

其中，/batch 是真正的规模化操作神器，它能将一项繁重的修改任务自动化并行处理。这些内置技能本身就是理解 Claude Code 设计哲学和最佳实践的绝佳范例。

好 Skill 的三个核心标准（重新审视）

1. 描述精准简短：重点不是“这个技能能做什么”，而是“应该在什么场景下使用这个技能”。
2. 具备完整工作流：包含明确的步骤、预期的输入输出格式以及清晰的停止条件，避免有始无终的开放式指令。
3. 正文保持精炼：SKILL.md 只放导航和核心约束，将大型参考资料、详细示例拆解到 supporting files 中。

最容易被忽视的一点：对于任何可能产生副作用的 Skill（例如执行部署、修改数据库），务必写上 disable-model-invocation: true，否则 Claude 可能会根据自己的判断自动触发它，带来意料之外的风险。

总结

特性	复杂度	实用度
目录结构 + 支持文件	★★	★★★★
Frontmatter 完整字段	★★	★★★★★
字符串替换 $ARGUMENTS	★★	★★★★★
动态注入 !`cmd`	★★★	★★★★
context: fork 子代理	★★★	★★★
权限控制	★★	★★★
作用域优先级	★	★★★★
内置 Bundled Skills	★	★★★★★

很多用户可能只挖掘了 Claude Code Skills 不足 10% 的潜力。当你开始有意识地将这 8 个特性组合运用时，Skill 就从一个简单的“保存的 prompt”演变成了强大、可编程的工作流扩展。如果你想与其他开发者交流更多类似的实战技巧，欢迎来 云栈社区 一起探讨。