ClaudeCode 扩展之王：自定义 Skills 让 Claude 拥有你的项目专属能力！把团队编码规范、部署流程、

使用 Skills 扩展 Claude

学习自：Claude Code Skills

Overview

Skills 扩展了 Claude Code 的功能。通过创建包含说明的 SKILL.md 文件，Claude 会在相关时自动使用它，或者你可以使用 /skill-name 直接调用。Skills 遵循 Agent Skills 开放标准，并支持自定义命令、捆绑依赖脚本、在 subagent 中运行等高级功能。自定义命令已合并到 skills 中，现有的 .claude/commands/ 文件继续工作。

捆绑 Skills

Claude Code 附带了几个预装的捆绑 skills，可直接使用：

Skill	用途
`/batch <instruction>`	在代码库中并行编排大规模更改，分解为多个独立单元，在隔离 git worktree 中生成后台代理每个单元，最后打开 PR
`/claude-api`	加载 Claude API 和 Agent SDK 参考资料，当代码导入 `anthropic`/`@anthropic-ai/sdk` 时自动激活
`/debug [description]`	启用调试日志记录并排查当前会话问题
`/loop [interval] <prompt>`	按间隔重复运行提示，适用于轮询部署、监督 PR
`/simplify [focus]`	审查最近更改的代码，查找重用、质量和效率问题并修复

入门：创建第一个 Skill

步骤

创建 skill 目录（个人 skills 在所有项目可用）：
```
mkdir -p ~/.claude/skills/explain-code
```

编写 SKILL.md：每个 skill 需要 YAML frontmatter + markdown 说明：

---
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 code to everyday things
2. **Draw a diagram**: Use ASCII art for flow/structure
3. **Walk through code**: Explain step-by-step
4. **Highlight a gotcha**: Common mistakes or misconceptions

测试：
- 让 Claude 自动调用：How does this code work?
- 或直接调用：/explain-code src/auth/login.ts

Skills 存储位置

位置决定作用范围和优先级（优先级高覆盖低）：

范围	路径
企业	托管设置（组织所有用户）
个人	`~/.claude/skills/<skill-name>/SKILL.md`（你的所有项目）
项目	`.claude/skills/<skill-name>/SKILL.md`（仅此项目）
插件	`<plugin>/skills/<skill-name>/SKILL.md`（启用插件的位置）

优先级：企业 > 个人 > 项目。插件使用 plugin-name:skill-name 命名空间，不冲突。

目录结构

每个 skill 是一个目录，SKILL.md 是必需入口点：

my-skill/
├── SKILL.md           # 主要说明（必需）
├── template.md        # Claude 要填写的模板（可选）
├── examples/
│   └── sample.md      # 示例输出（可选）
└── scripts/
    └── validate.sh    # Claude 可执行脚本（可选）

从 SKILL.md 中引用支持文件，保持主 skill 简洁。提示：保持 SKILL.md 在 500 行以下，详细参考移到单独文件。

配置 Skills

Frontmatter 参考

所有字段都是可选的（推荐 description）：

字段	说明
`name`	Skill 名称，变成 `/slash-command`，省略则使用目录名（小写+数字+连字符，最多 64 字符）
`description`	Skill 功能和何时使用，Claude 用它决定何时自动加载，推荐填写
`argument-hint`	自动完成时显示的参数提示，如 `[issue-number]`
`disable-model-invocation`	`true` 防止 Claude 自动加载，用于手动触发的工作流（默认 `false`）
`user-invocable`	`false` 从 `/` 菜单隐藏，用于仅 Claude 调用的背景知识（默认 `true`）
`allowed-tools`	skill 活跃时无需请求权限即可使用的工具
`model`	skill 活跃时使用的模型
`effort`	努力级别：`low`/`medium`/`high`/`max`（仅 Opus 4.6），覆盖会话级别
`context`	设置 `fork` 在分叉的 subagent 上下文中运行
`agent`	`context: fork` 时使用的 subagent 类型
`hooks`	限定于此 skill 生命周期的 hooks
`paths`	Glob 模式，仅处理匹配文件时自动激活
`shell`	内联 `!`command `块使用的 shell：`bash`（默认）或` powershell`

控制谁调用 Skill

两个字段限制调用权限：

Frontmatter	用户可调用	Claude 可调用	说明
（默认）	是	是	描述始终在上下文，调用时加载完整 skill
`disable-model-invocation: true`	是	否	只有你能调用，用于有副作用的工作流（如 `/deploy`、`/commit`）
`user-invocable: false`	否	是	只有 Claude 能调用，用于背景知识，用户直接调用无意义

字符串替换（动态参数）

Skills 支持动态值替换：

变量	说明
`$ARGUMENTS`	调用 skill 时传递的所有参数
`$ARGUMENTS[N]`	按 0 基索引访问特定参数，如 `$ARGUMENTS[0]`
`$N`	`$ARGUMENTS[N]` 简写，如 `$0` 第一个参数
`${CLAUDE_SESSION_ID}`	当前会话 ID
`${CLAUDE_SKILL_DIR}`	skill 目录路径，用于引用捆绑的脚本

示例：按编号修复 GitHub issue

---
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. Understand the requirements
3. Implement the fix

运行 /fix-issue 123 后，$ARGUMENTS 被替换为 123。如果 skill 不包含 $ARGUMENTS，参数会自动追加到末尾。

多个参数示例：

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

运行 /migrate-component SearchBar React Vue 正确替换各参数。

高级模式

注入动态上下文

使用 !`<command>` 语法，在 Claude 看到 skill 内容之前先运行 shell 命令，输出替换占位符。

示例：总结 PR skill：

---
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...

执行顺序：

!`command` 立即执行
输出替换占位符
Claude 接收包含实际数据的完整提示

这是预处理，Claude 只看到最终结果。

在 Subagent 中运行 Skills

添加 context: fork 让 skill 在隔离上下文运行，skill 内容成为驱动 subagent 的提示，无法访问主对话历史。

示例：深度研究 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

执行流程：

创建新隔离上下文
Subagent 接收 skill 内容作为提示
agent 字段决定执行环境（模型、工具、权限）
结果总结返回主对话

agent 可以是内置代理（Explore/Plan/general-purpose）或自定义 subagent，省略默认为 general-purpose。

限制 Skill 访问

控制 Claude 可调用哪些 skills 的三种方式：

禁用所有 skills：在 /permissions 的 deny 规则添加 Skill
允许/拒绝特定 skills：使用权限规则
```
Allow: Skill(commit), Skill(review-pr *)
Deny: Skill(deploy *)
```
语法：Skill(name) 精确匹配，Skill(name *) 前缀匹配（任何参数）
隐藏单个 skill：添加 disable-model-invocation: true 从上下文中完全删除

user-invocable 仅控制菜单可见性，不控制 Skill 工具访问。使用 disable-model-invocation 阻止程序调用。

共享 Skills

不同范围分发方式：

项目 skills：将 .claude/skills/ 提交到版本控制，团队共享
插件：在插件中创建 skills/ 目录分发
托管：通过托管设置部署组织范围内

生成视觉输出示例

Skills 可以捆绑任意语言脚本，生成交互式 HTML 输出。以下是代码库可视化工具示例：

目录结构：

~/.claude/skills/codebase-visualizer/
├── SKILL.md
└── scripts/
    └── visualize.py

SKILL.md:

---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python *)
---

Generate an interactive HTML tree view that shows your project's file structure.

Run:

```bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .
```

创建 codebase-map.html，并在浏览器中打开它

故障排除

Skill 未触发

检查描述是否包含用户会自然说的关键字
验证 skill 是否出现在 What skills are available? 中
重新表述请求更接近描述
如果是用户可调用，直接用 /skill-name 调用

Skill 触发过于频繁

使描述更具体
如果只想手动调用，添加 disable-model-invocation: true

Skill 描述被截断

所有 skill 描述加载到上下文时会限制字符预算（默认为上下文的 1%，最少 8000 字符）
解决方法：前置关键用例，每个描述限制 250 字符以内
提高限制：设置 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量

核心要点

Skills 是扩展 Claude Code 的方式：创建自定义命令、添加领域知识、自动化工作流
灵活的调用控制：可自动调用、仅用户手动调用、仅 Claude 使用，满足不同场景
支持在 subagent 中隔离运行：使用 context: fork + agent: X 在独立上下文执行任务
动态上下文注入：!`command` 预处理将命令输出插入提示，实现实时数据获取
参数传递：通过 $ARGUMENTS、$0、$1 等轻松访问调用参数
目录结构支持附加文件：SKILL.md + 模板/示例/脚本，保持组织清晰
多级作用范围：个人（所有项目）、项目（团队共享）、企业（组织范围）、插件分发
可访问控制：通过权限规则允许/禁止特定 skills，保证安全