Agent Skills 指南

Agent Skills 是可复用的、基于文件系统的能力，用于扩展 Claude 的功能。它们将特定领域的专业知识、工作流和最佳实践打包成可发现的组件，Claude 在相关场景下会自动使用。

概览

Agent Skills 是将通用代理转化为专家的模块化能力。与提示（一次性任务的对话级指令）不同，Skills 按需加载，消除了在多个对话中重复提供相同指导的需要。

主要好处

• 专业化 Claude：为特定领域任务定制能力
• 减少重复：创建一次，跨对话自动使用
• 组合能力：组合 Skills 构建复杂工作流
• 扩展工作流：跨多个项目和团队复用 skills
• 保持质量：将最佳实践直接嵌入工作流

Skills 遵循 Agent Skills 开放标准，适用于多种 AI 工具。Claude Code 通过额外功能（如调用控制、subagent 执行和动态上下文注入）扩展了该标准。

注意：自定义斜杠命令已合并到 skills 中。.claude/commands/ 文件仍然有效并支持相同的 frontmatter 字段。新开发推荐使用 Skills。当两者存在于相同路径时（例如 .claude/commands/review.md 和 .claude/skills/review/SKILL.md），skill 优先。

Skills 的工作方式：渐进式披露

Skills 利用渐进式披露架构——Claude 按需分阶段加载信息，而不是预先消耗上下文。这实现了高效的上下文管理，同时保持无限的可扩展性。

三层加载

    graph TB
    subgraph "第 1 层：元数据（始终加载）"
        A["YAML Frontmatter"]
        A1["每个 skill 约 100 tokens"]
        A2["name + description"]
    end

    subgraph "第 2 层：指令（触发时加载）"
        B["SKILL.md 正文"]
        B1["低于 5k tokens"]
        B2["工作流和指导"]
    end

    subgraph "第 3 层：资源（按需加载）"
        C["捆绑文件"]
        C1["实际上无限制"]
        C2["脚本、模板、文档"]
    end

    A --> B
    B --> C
  

这意味着你可以安装很多 Skills 而不会产生上下文惩罚——Claude 只知道每个 Skill 的存在和何时使用它，直到实际触发。

Skill 加载流程

    sequenceDiagram
    participant 用户
    participant Claude
    participant 系统
    participant SkillInst as Skill 指令
    participant SkillRes as Skill 资源

    用户->>Claude: "审查这段代码的安全问题"
    Claude->>系统: 检查可用 skills（元数据）
    系统-->>Claude: 启动时加载的 skill 描述
    Claude->>Claude: 将请求与 skill 描述匹配
    Claude->>SkillInst: 读取 code-review/SKILL.md
    SkillInst-->>Claude: 第 2 层：指令已加载
    Claude->>Claude: 判断：需要模板？
    Claude->>SkillRes: 读取 templates/checklist.md
    SkillRes-->>Claude: 第 3 层：模板已加载
    Claude->>Claude: 执行 skill 指令
    Claude->>用户: 全面的代码审查
  

Skill 类型与位置

当 skills 在不同层级共享相同名称时，更高优先级的位置优先：企业级 > 个人 > 项目。插件 skills 使用 plugin-name:skill-name 命名空间，因此不会冲突。

Subagent skill 发现（v2.1.133+）：Subagents 现在通过 Skill 工具发现项目、用户和插件 skills，与主会话相同。早期版本将 subagents 限制在其自己的嵌入集中，这意味着 skill+subagent 工作流会静默降级；从 v2.1.133 开始，相同的 skill 目录对两者都可见。

自动发现

嵌套目录：当你处理子目录中的文件时，Claude Code 会自动从嵌套的 .claude/skills/ 目录中发现 skills。例如，如果你正在编辑 packages/frontend/ 中的文件，Claude Code 也会在 packages/frontend/.claude/skills/ 中查找 skills。这支持 packages 有自己 skills 的 monorepo 设置。

--add-dir 目录：通过 --add-dir 添加的目录中的 skills 会自动加载，并具有实时更改检测。对这些目录中 skill 文件的任何编辑都会立即生效，无需重启 Claude Code。

描述预算：Skill 描述（第 1 层元数据）限制为上下文窗口的 1%（后备：8,000 字符）。如果你安装了很多 skills，描述可能会被缩短。所有 skill 名称始终包含在内，但描述会被修剪以适应。在描述中前置关键用例。使用 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量覆盖预算。

创建自定义 Skills

基本目录结构

my-skill/
├── SKILL.md           # 主指令（必需）
├── template.md        # Claude 填写的模板
├── examples/
│   └── sample.md      # 展示期望格式的示例输出
└── scripts/
    └── validate.sh    # Claude 可执行的脚本

SKILL.md 格式

---
name: your-skill-name
description: 这个 Skill 做什么以及何时使用的简要描述
---

# 你的 Skill 名称

## 指令
为 Claude 提供清晰的、分步的指导。

## 示例
展示使用此 Skill 的具体示例。

必填字段

• name：仅小写字母、数字、连字符（最多 64 个字符）。不能包含 “anthropic” 或 “claude”。
• description：Skill 做什么以及何时使用（最多 1024 个字符）。这对 Claude 知道何时激活 skill 至关重要。

可选 Frontmatter 字段

---
name: my-skill
description: 这个 skill 做什么以及何时使用
argument-hint: "[filename] [format]"        # 自动完成的提示
disable-model-invocation: true              # 仅用户可以调用
user-invocable: false                       # 从斜杠菜单中隐藏
allowed-tools: Read, Grep, Glob             # 限制工具访问
model: opus                                 # 使用特定模型
effort: high                                # 努力级别覆盖（low、medium、high、xhigh、max）
context: fork                               # 在隔离的 subagent 中运行
agent: Explore                              # subagent 类型（配合 context: fork）
shell: bash                                 # 命令使用的 shell：bash（默认）或 powershell
hooks:                                      # Skill 范围的 hooks
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
paths: "src/api/**/*.ts"               # 限制 skill 激活的 glob 模式
---

Skill 内容类型

Skills 可以包含两种类型的内容，每种适合不同的目的：

参考内容

添加 Claude 应用到当前工作的知识——约定、模式、风格指南、领域知识。在对话上下文中内联运行。

---
name: api-conventions
description: 此代码库的 API 设计模式
---

编写 API 端点时：
- 使用 RESTful 命名约定
- 返回一致的错误格式
- 包含请求验证

任务内容

特定操作的分步指令。通常通过 /skill-name 直接调用。

---
name: deploy
description: 将应用程序部署到生产环境
context: fork
disable-model-invocation: true
---

部署应用程序：
1. 运行测试套件
2. 构建应用程序
3. 推送到部署目标

控制 Skill 调用

默认情况下，你和 Claude 都可以调用任何 skill。两个 frontmatter 字段控制三种调用模式：

使用 disable-model-invocation: true 用于有副作用的工作流：/commit、/deploy、/send-slack-message。你不希望 Claude 因为代码看起来准备好了就决定部署。

使用 user-invocable: false 用于不可作为命令操作的背景知识。legacy-system-context skill 解释旧系统的工作方式——对 Claude 有用，但对用户不是有意义的操作。

字符串替换

Skills 支持在 skill 内容到达 Claude 之前解析的动态值：

示例：

---
name: fix-issue
description: 修复 GitHub issue
---

按照我们的编码标准修复 GitHub issue $ARGUMENTS。
1. 阅读 issue 描述
2. 实现修复
3. 编写测试
4. 创建提交

运行 /fix-issue 123 会将 $ARGUMENTS 替换为 123。

注入动态上下文

!`command` 语法在 skill 内容发送给 Claude 之前运行 shell 命令：

---
name: pr-summary
description: 总结拉取请求中的更改
context: fork
agent: Explore
---

## 拉取请求上下文
- PR diff：!`gh pr diff`
- PR 评论：!`gh pr view --comments`
- 更改的文件：!`gh pr diff --name-only`

## 你的任务
总结这个拉取请求...

命令立即执行；Claude 只看到最终输出。默认情况下，命令在 bash 中运行。在 frontmatter 中设置 shell: powershell 以使用 PowerShell。

在 Subagent 中运行 Skills

添加 context: fork 以在隔离的 subagent 上下文中运行 skill。Skill 内容成为拥有自己上下文窗口的专用 subagent 的任务，保持主对话整洁。

agent 字段指定使用哪种代理类型：

Frontmatter 示例：

---
context: fork
agent: Explore
---

完整 skill 示例：

---
name: deep-research
description: 全面研究一个主题
context: fork
agent: Explore
---

彻底研究 $ARGUMENTS：
1. 使用 Glob 和 Grep 查找相关文件
2. 阅读和分析代码
3. 总结发现并附带具体文件引用

实战示例

示例 1：代码审查 Skill

目录结构：

~/.claude/skills/code-review/
├── SKILL.md
├── templates/
│   ├── review-checklist.md
│   └── finding-template.md
└── scripts/
    ├── analyze-metrics.py
    └── compare-complexity.py

文件： ~/.claude/skills/code-review/SKILL.md

---
name: code-review-specialist
description: 全面的代码审查，包含安全、性能和质量分析。当用户要求审查代码、分析代码质量、评估拉取请求或提到代码审查、安全分析或性能优化时使用。
---

# 代码审查 Skill

此 skill 提供全面的代码审查能力，重点关注：

1. **安全分析**
   - 认证/授权问题
   - 数据暴露风险
   - 注入漏洞
   - 密码学弱点

2. **性能审查**
   - 算法效率（大 O 分析）
   - 内存优化
   - 数据库查询优化
   - 缓存机会

3. **代码质量**
   - SOLID 原则
   - 设计模式
   - 命名约定
   - 测试覆盖率

4. **可维护性**
   - 代码可读性
   - 函数大小（应 < 50 行）
   - 圈复杂度
   - 类型安全

## 审查模板

对于审查的每段代码，提供：

### 摘要
- 整体质量评估（1-5）
- 关键发现数量
- 建议的重点领域

### 关键问题（如有）
- **问题**：清晰的描述
- **位置**：文件和行号
- **影响**：为什么重要
- **严重性**：关键/高/中
- **修复**：代码示例

详细检查清单请参见 [templates/review-checklist.md]((templates/review-checklist.md.en.md)。

示例 2：代码库可视化 Skill

一个生成交互式 HTML 可视化的 skill：

目录结构：

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

文件： ~/.claude/skills/codebase-visualizer/SKILL.md

---
name: codebase-visualizer
description: 生成代码库的交互式可折叠树可视化。当探索新仓库、理解项目结构或识别大文件时使用。
allowed-tools: Bash(python *)
---

# 代码库可视化器

生成交互式 HTML 树视图，展示项目的文件结构。

## 用法

从项目根目录运行可视化脚本：

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

这会创建 `codebase-map.html` 并在默认浏览器中打开。

## 可视化内容

- **可折叠目录**：点击文件夹展开/折叠
- **文件大小**：显示在每个文件旁边
- **颜色**：不同文件类型不同颜色
- **目录汇总**：显示每个文件夹的聚合大小

捆绑的 Python 脚本处理繁重的工作，而 Claude 负责编排。

示例 3：部署 Skill（仅用户调用）

---
name: deploy
description: 将应用程序部署到生产环境
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *)
---

将 $ARGUMENTS 部署到生产环境：

1. 运行测试套件：`npm test`
2. 构建应用程序：`npm run build`
3. 推送到部署目标
4. 验证部署成功
5. 报告部署状态

示例 4：品牌语气 Skill（背景知识）

---
name: brand-voice
description: 确保所有沟通符合品牌语气和语调指南。当创建营销文案、客户沟通或面向公众的内容时使用。
user-invocable: false
---

## 语调
- **友好但专业**——平易近人但不随意
- **清晰简洁**——避免术语
- **自信**——我们知道我们在做什么
- **有同理心**——理解用户需求

## 写作准则
- 称呼读者时使用"你"
- 使用主动语态
- 句子保持在 20 个词以内
- 从价值主张开始

模板请参见 [templates/](templates/)。

示例 5：CLAUDE.md 生成 Skill

---
name: claude-md
description: 创建或更新 CLAUDE.md 文件，遵循最佳实践以优化 AI 代理入职。当用户提到 CLAUDE.md、项目文档或 AI 入职时使用。
---

## 核心原则

**LLM 是无状态的**：CLAUDE.md 是每个对话中自动包含的唯一文件。

### 黄金法则

1. **少即是多**：保持在 300 行以内（理想情况下 100 行以内）
2. **普遍适用性**：仅包含与每个会话相关的信息
3. **不要把 Claude 当作 Linter**：使用确定性工具代替
4. **永远不要自动生成**：手动精心制作，仔细考虑

## 必要部分

- **项目名称**：简短的一行描述
- **技术栈**：主要语言、框架、数据库
- **开发命令**：安装、测试、构建命令
- **关键约定**：仅非显而易见的、高影响的约定
- **已知问题/陷阱**：容易让开发者犯错的地方

示例 6：带脚本的重构 Skill

目录结构：

refactor/
├── SKILL.md
├── references/
│   ├── code-smells.md
│   └── refactoring-catalog.md
├── templates/
│   └── refactoring-plan.md
└── scripts/
    ├── analyze-complexity.py
    └── detect-smells.py

文件： refactor/SKILL.md

---
name: code-refactor
description: 基于 Martin Fowler 方法论的系统化代码重构。当用户要求重构代码、改进代码结构、减少技术债务或消除代码异味时使用。
---

# 代码重构 Skill

分阶段方法，强调以测试为支撑的安全、增量更改。

## 工作流

阶段 1：研究与分析 → 阶段 2：测试覆盖评估 →
阶段 3：代码异味识别 → 阶段 4：重构计划创建 →
阶段 5：增量实施 → 阶段 6：审查与迭代

## 核心原则

1. **行为保持**：外部行为必须保持不变
2. **小步骤**：进行微小的、可测试的更改
3. **测试驱动**：测试是安全网
4. **持续性**：重构是持续的，不是一次性的

代码异味目录请参见 [references/code-smells.md]((references/code-smells.md.en.md)。
重构技术请参见 [references/refactoring-catalog.md]((references/refactoring-catalog.md.en.md)。

支持文件

Skills 可以在其目录中包含 SKILL.md 之外的多个文件。这些支持文件（模板、示例、脚本、参考文档）让你保持主 skill 文件聚焦，同时为 Claude 提供可以按需加载的额外资源。

my-skill/
├── SKILL.md              # 主指令（必需，保持在 500 行以内）
├── templates/            # Claude 填写的模板
│   └── output-format.md
├── examples/             # 展示期望格式的示例输出
│   └── sample-output.md
├── references/           # 领域知识和规范
│   └── api-spec.md
└── scripts/              # Claude 可执行的脚本
    └── validate.sh

支持文件指南：

• 保持 SKILL.md 在 500 行以内。将详细参考资料、大型示例和规范移动到单独的文件中。
• 从 SKILL.md 引用附加文件时使用相对路径（例如 [API reference]((references/api-spec.md.en.md)）。
• 支持文件在第 3 层（按需）加载，因此在 Claude 实际读取它们之前不会消耗上下文。

管理 Skills

查看可用 Skills

直接询问 Claude：

有哪些 Skills 可用？

或检查文件系统：

# 列出个人 Skills
ls ~/.claude/skills/

# 列出项目 Skills
ls .claude/skills/

提示（v2.1.121+）： 输入以过滤 /skills 交互式菜单——当安装了很多 skills 时很有用。

测试 Skill

两种测试方式：

让 Claude 自动调用，通过询问匹配描述的内容：

你能帮我审查这段代码的安全问题吗？

或直接调用，使用 skill 名称：

/code-review src/auth/login.ts

更新 Skill

直接编辑 SKILL.md 文件。更改在下次 Claude Code 启动时生效。

# 个人 Skill
code ~/.claude/skills/my-skill/SKILL.md

# 项目 Skill
code .claude/skills/my-skill/SKILL.md

限制 Claude 对 Skill 的访问

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

禁用所有 skills，在 /permissions 中：

# 添加到拒绝规则：
Skill

允许或拒绝特定 skills：

# 仅允许特定 skills
Skill(commit)
Skill(review-pr *)

# 拒绝特定 skills
Skill(deploy *)

隐藏单个 skills，通过在其 frontmatter 中添加 disable-model-invocation: true。

控制 Skill 覆盖行为（skillOverrides）

当项目 skill 和用户 skill 共享相同名称时，项目默认优先。skillOverrides 设置（v2.1.129+）允许你调整这一点。添加到 ~/.claude/settings.json 或项目 .claude/settings.json：

{
  "skillOverrides": "name-only"
}

接受的值：

当团队策略说"用户定义的 skills 必须始终优先"（"off"）或"仅允许窄名称匹配覆盖"（"name-only"）时很有用。

最佳实践

1. 让描述具体

• 差（模糊）：“帮助处理文档”
• 好（具体）：“从 PDF 文件中提取文本和表格，填写表单，合并文档。当处理 PDF 文件或用户提到 PDF、表单或文档提取时使用。”

2. 保持 Skills 聚焦

• 一个 Skill = 一个能力
• ✅ “PDF 表单填写”
• ❌ “文档处理”（太宽泛）

3. 包含触发词

在描述中添加与用户请求匹配的关键词：

description: 分析 Excel 电子表格，生成数据透视表，创建图表。当处理 Excel 文件、电子表格或 .xlsx 文件时使用。

4. 保持 SKILL.md 在 500 行以内

将详细参考资料移动到 Claude 按需加载的单独文件中。

5. 引用支持文件

## 附加资源

- 完整 API 详情请参见 [reference.md]((reference.md.en.md)
- 使用示例请参见 [examples.md]((examples.md.en.md)

应该做的

• 使用清晰、描述性的名称
• 包含全面的指令
• 添加具体示例
• 打包相关的脚本和模板
• 用真实场景测试
• 记录依赖关系

不应该做的

• 不要为一次性任务创建 skills
• 不要重复现有功能
• 不要让 skills 太宽泛
• 不要跳过 description 字段
• 不要安装未经审计的不可信来源的 skills

故障排查

快速参考

Skill 未触发

如果 Claude 在预期时未使用你的 skill：

1. 检查描述是否包含用户自然会说的关键词
2. 验证 skill 是否在询问"有哪些 skills 可用？“时出现
3. 尝试重新组织请求以匹配描述
4. 直接用 /skill-name 调用测试

Skill 触发太频繁

如果 Claude 在你不想时使用了你的 skill：

1. 使描述更具体
2. 添加 disable-model-invocation: true 用于仅手动调用

Claude 看不到所有 Skills

Skill 描述加载限制为上下文窗口的 1%（后备：8,000 字符）。每个条目无论预算如何都限制为 250 个字符。运行 /context 检查被排除 skills 的警告。使用 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量覆盖预算。

安全注意事项

仅使用来自可信来源的 Skills。 Skills 通过指令和代码为 Claude 提供能力——恶意 Skill 可以指示 Claude 以有害方式调用工具或执行代码。

关键安全注意事项：

• 彻底审计：审查 Skill 目录中的所有文件
• 外部来源有风险：从外部 URL 获取的 skills 可能被篡改
• 工具滥用：恶意 Skills 可以以有害方式调用工具
• 像安装软件一样对待：仅使用来自可信来源的 Skills

禁用 skills 中的 shell 替换

Skills 支持 !`command` 语法，在 Claude 看到之前将 shell 命令的输出注入到提示中。在安全敏感的环境（共享企业部署、锁定的 CI 运行器）中，你可以通过 disableSkillShellExecution 设置（在 v2.1.91 中添加）完全禁用此替换：

// ~/.claude/settings.json 或受管策略
{
  "disableSkillShellExecution": true
}

当 disableSkillShellExecution 为 true 时，skill 中的任何 !`command` 标记会保留为字面文本而不是被执行——移除了 skill 级别的 shell 注入攻击面，而不禁用 skills 本身。考虑与 allowedTools 允许列表结合使用以实现纵深防御。

Skills vs 其他功能

内置 Skills

Claude Code 附带几个内置 skills，无需安装即可使用：

这些 skills 开箱即用，无需安装或配置。它们遵循与自定义 skills 相同的 SKILL.md 格式。

共享 Skills

项目 Skills（团队共享）

1. 在 .claude/skills/ 中创建 Skill
2. 提交到 git
3. 团队成员拉取更改——Skills 立即可用

个人 Skills

# 复制到个人目录
cp -r my-skill ~/.claude/skills/

# 让脚本可执行
chmod +x ~/.claude/skills/my-skill/scripts/*.py

插件分发

在插件的 skills/ 目录中打包 skills 以进行更广泛的分发。

继续深入：Skill 集合和 Skill 管理器

一旦你开始认真构建 skills，两件事变得必不可少：一个经过验证的 skills 库和一个管理工具。

luongnv89/skills — 我在几乎所有项目中每天使用的 skills 集合。亮点包括 logo-designer（动态生成项目 logo）和 ollama-optimizer（为你的硬件调整本地 LLM 性能）。如果你想开箱即用的 skills，这是一个很好的起点。

luongnv89/asm — Agent Skill Manager。处理 skill 开发、重复检测和测试。asm link 命令让你可以在任何项目中测试 skill 而无需复制文件——一旦你有超过少量 skills，这非常必要。

附加资源

• 官方 Skills 文档
• Agent Skills 架构博客
• Skills 仓库 - 开箱即用的 skills 集合
• 斜杠命令指南 - 用户发起的快捷方式
• Subagents 指南 - 委派的 AI 代理
• Memory 指南 - 持久上下文
• MCP（模型上下文协议） - 实时外部数据
• Hooks 指南 - 事件驱动自动化

最后更新：2026 年 5 月 9 日 Claude Code 版本：2.1.138 来源：

• https://code.claude.com/docs/en/skills
• https://code.claude.com/docs/en/settings
• https://code.claude.com/docs/en/changelog 兼容模型：Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5