代理技能指南
代理技能是基于文件系统的可复用能力，用于扩展 Claude 的功能。它们将特定领域的专业知识、工作流程和最佳实践打包成可发现的组件，供 Claude 在相关场景下自动使用。
概述
代理技能是模块化能力，可将通用代理转变为专家。与提示词（针对一次性任务的对话级指令）不同，技能按需加载，无需在多次对话中反复提供相同的指导。
核心优势
- 专业化 Claude：针对特定领域任务定制能力
- 减少重复：一次创建，跨对话自动使用
- 组合能力：组合多个技能以构建复杂工作流
- 扩展工作流：在多个项目和团队中复用技能
- 保证质量：将最佳实践直接嵌入工作流
技能遵循 Agent Skills 开放标准，可在多种 AI 工具中通用。Claude Code 在此标准基础上扩展了额外功能，如调用控制、子代理执行和动态上下文注入。
注意：自定义斜杠命令已合并到技能中。
.claude/commands/中的文件仍然有效，并支持相同的前置元数据字段。新开发推荐使用技能。当两者在相同路径下同时存在时（例如.claude/commands/review.md和.claude/skills/review/SKILL.md），技能优先生效。
技能工作原理：渐进式披露
技能采用渐进式披露架构——Claude 按需分阶段加载信息，而非预先消耗上下文。这样既能高效管理上下文，又能保持无限可扩展性。
三级加载机制
| 级别 | 加载时机 | Token 消耗 | 内容 |
|---|---|---|---|
| 第一级：元数据 | 始终（启动时） | 每个技能约 100 个 token | YAML 前置元数据中的 name 和 description |
| 第二级：指令 | 触发技能时 | 不超过 5k token | 包含指令和指导的 SKILL.md 正文 |
| 第三级及以上：资源 | 按需加载 | 实际上不受限制 | 通过 bash 执行的捆绑文件，内容不载入上下文 |
这意味着安装多个技能不会产生上下文负担——在实际触发之前，Claude 只知道每个技能的存在及其适用场景。
技能加载流程
技能类型与位置
| 类型 | 位置 | 作用域 | 是否共享 | 适用场景 |
|---|---|---|---|---|
| 企业级 | 托管设置 | 所有组织用户 | 是 | 组织范围的标准 |
| 个人级 | ~/.claude/skills/<skill-name>/SKILL.md | 个人 | 否 | 个人工作流 |
| 项目级 | .claude/skills/<skill-name>/SKILL.md | 团队 | 是（通过 git） | 团队标准 |
| 插件级 | <plugin>/skills/<skill-name>/SKILL.md | 启用范围内 | 视情况而定 | 与插件捆绑 |
当同名技能存在于不同层级时，优先级较高的位置生效：企业级 > 个人级 > 项目级。插件技能使用 plugin-name:skill-name 命名空间，因此不会产生冲突。
自动发现
嵌套目录：当您处理子目录中的文件时，Claude Code 会自动从嵌套的 .claude/skills/ 目录中发现技能。例如，如果您正在编辑 packages/frontend/ 中的文件，Claude Code 也会在 packages/frontend/.claude/skills/ 中查找技能。这支持各包拥有自己技能的 monorepo 场景。
--add-dir 目录：通过 --add-dir 添加的目录中的技能会自动加载，并支持实时变更检测。对这些目录中技能文件的任何编辑都会立即生效，无需重启 Claude Code。
描述预算：技能描述（第一级元数据）上限为上下文窗口的 2%（后备值：16,000 个字符）。如果安装了大量技能，部分技能可能被排除在外。运行 /context 查看警告信息。可通过 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量覆盖预算。
创建自定义技能
基本目录结构
my-skill/
├── SKILL.md # 主要指令（必需）
├── template.md # 供 Claude 填写的模板
├── examples/
│ └── sample.md # 展示预期格式的示例输出
└── scripts/
└── validate.sh # Claude 可执行的脚本SKILL.md 格式
yaml
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---
# Your Skill Name
## Instructions
Provide clear, step-by-step guidance for Claude.
## Examples
Show concrete examples of using this Skill.必填字段
- name：仅限小写字母、数字、连字符（最多 64 个字符）。不能包含 "anthropic" 或 "claude"。
- description：技能的功能及使用时机（最多 1024 个字符）。这对 Claude 判断何时激活技能至关重要。
可选前置元数据字段
yaml
---
name: my-skill
description: What this skill does and when to use it
argument-hint: "[filename] [format]" # 自动补全提示
disable-model-invocation: true # 仅用户可调用
user-invocable: false # 从斜杠菜单中隐藏
allowed-tools: Read, Grep, Glob # 限制工具访问
model: opus # 指定使用的模型
effort: high # 努力程度覆盖（low, medium, high, max）
context: fork # 在隔离的子代理中运行
agent: Explore # 代理类型（与 context: fork 配合使用）
shell: bash # 命令使用的 Shell：bash（默认）或 powershell
hooks: # 技能作用域的钩子
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate.sh"
---| 字段 | 描述 |
|---|---|
name | 仅限小写字母、数字、连字符（最多 64 个字符）。不能包含 "anthropic" 或 "claude"。 |
description | 技能的功能及使用时机（最多 1024 个字符）。对自动调用匹配至关重要。 |
argument-hint | 在 / 自动补全菜单中显示的提示（例如 "[filename] [format]"）。 |
disable-model-invocation | true = 仅用户可通过 /name 调用。Claude 不会自动调用。 |
user-invocable | false = 从 / 菜单中隐藏。只有 Claude 可以自动调用。 |
allowed-tools | 技能无需权限提示即可使用的工具，以逗号分隔。 |
model | 技能激活时的模型覆盖（例如 opus、sonnet）。 |
effort | 技能激活时的努力程度覆盖：low、medium、high 或 max。 |
context | fork 表示在具有独立上下文窗口的分叉子代理上下文中运行技能。 |
agent | 使用 context: fork 时的子代理类型（例如 Explore、Plan、general-purpose）。 |
shell | 用于 !`command` 替换和脚本的 Shell：bash（默认）或 powershell。 |
hooks | 作用于本技能生命周期的钩子（格式与全局钩子相同）。 |
技能内容类型
技能可包含两种类型的内容，各自适用于不同目的：
参考内容
添加 Claude 应用于当前工作的知识——规范、模式、风格指南、领域知识。与对话上下文内联运行。
yaml
---
name: api-conventions
description: API design patterns for this codebase
---
When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation任务内容
用于特定操作的逐步指令，通常通过 /skill-name 直接调用。
yaml
---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---
Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target控制技能调用
默认情况下，您和 Claude 均可调用任何技能。两个前置元数据字段控制三种调用模式：
| 前置元数据 | 您可以调用 | Claude 可以调用 |
|---|---|---|
| （默认） | 是 | 是 |
disable-model-invocation: true | 是 | 否 |
user-invocable: false | 否 | 是 |
使用 disable-model-invocation: true 适用于具有副作用的工作流：/commit、/deploy、/send-slack-message。您不希望 Claude 因为代码看起来已就绪就擅自决定部署。
使用 user-invocable: false 适用于不作为命令使用的背景知识。legacy-system-context 技能解释旧系统的工作原理——对 Claude 有用，但对用户来说不是有意义的操作。
字符串替换
技能支持动态值，这些值在技能内容传递给 Claude 之前会被解析：
| 变量 | 描述 |
|---|---|
$ARGUMENTS | 调用技能时传递的所有参数 |
$ARGUMENTS[N] 或 $N | 按索引访问特定参数（从 0 开始） |
${CLAUDE_SESSION_ID} | 当前会话 ID |
${CLAUDE_SKILL_DIR} | 包含技能 SKILL.md 文件的目录 |
!`command` | 动态上下文注入——运行 Shell 命令并将输出内联 |
示例：
yaml
---
name: fix-issue
description: Fix a GitHub issue
---
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。
注入动态上下文
!`command` 语法会在技能内容发送给 Claude 之前执行 Shell 命令：
yaml
---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
---
## 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...命令立即执行；Claude 只看到最终输出。默认情况下，命令在 bash 中运行。在前置元数据中设置 shell: powershell 可改为使用 PowerShell。
在子代理中运行技能
添加 context: fork 可在隔离的子代理上下文中运行技能。技能内容成为专属子代理的任务，该子代理拥有独立的上下文窗口，使主对话保持整洁。
agent 字段指定使用的代理类型：
| 代理类型 | 适用场景 |
|---|---|
Explore | 只读研究、代码库分析 |
Plan | 创建实施计划 |
general-purpose | 需要所有工具的广泛任务 |
| 自定义代理 | 在配置中定义的专用代理 |
示例前置元数据：
yaml
---
context: fork
agent: Explore
---完整技能示例：
yaml
---
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实际示例
示例一：代码审查技能
目录结构：
~/.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
yaml
---
name: code-review-specialist
description: Comprehensive code review with security, performance, and quality analysis. Use when users ask to review code, analyze code quality, evaluate pull requests, or mention code review, security analysis, or performance optimization.
---
# Code Review Skill
This skill provides comprehensive code review capabilities focusing on:
1. **Security Analysis**
- Authentication/authorization issues
- Data exposure risks
- Injection vulnerabilities
- Cryptographic weaknesses
2. **Performance Review**
- Algorithm efficiency (Big O analysis)
- Memory optimization
- Database query optimization
- Caching opportunities
3. **Code Quality**
- SOLID principles
- Design patterns
- Naming conventions
- Test coverage
4. **Maintainability**
- Code readability
- Function size (should be < 50 lines)
- Cyclomatic complexity
- Type safety
## Review Template
For each piece of code reviewed, provide:
### Summary
- Overall quality assessment (1-5)
- Key findings count
- Recommended priority areas
### Critical Issues (if any)
- **Issue**: Clear description
- **Location**: File and line number
- **Impact**: Why this matters
- **Severity**: Critical/High/Medium
- **Fix**: Code example
For detailed checklists, see [templates/review-checklist.md](templates/review-checklist.md).示例二：代码库可视化技能
一个生成交互式 HTML 可视化图表的技能：
目录结构：
~/.claude/skills/codebase-visualizer/
├── SKILL.md
└── scripts/
└── visualize.py文件： ~/.claude/skills/codebase-visualizer/SKILL.md
yaml
---
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 *)
---
# Codebase Visualizer
Generate an interactive HTML tree view showing your project's file structure.
## Usage
Run the visualization script from your project root:
```bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .This creates codebase-map.html and opens it in your default browser.
What the visualization shows
- Collapsible directories: Click folders to expand/collapse
- File sizes: Displayed next to each file
- Colors: Different colors for different file types
- Directory totals: Shows aggregate size of each folder
捆绑的 Python 脚本负责繁重的处理工作，而 Claude 负责编排。
### 示例三：部署技能（仅用户调用）
```yaml
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *)
---
Deploy $ARGUMENTS to production:
1. Run the test suite: `npm test`
2. Build the application: `npm run build`
3. Push to the deployment target
4. Verify the deployment succeeded
5. Report deployment status示例四：品牌声音技能（背景知识）
yaml
---
name: brand-voice
description: Ensure all communication matches brand voice and tone guidelines. Use when creating marketing copy, customer communications, or public-facing content.
user-invocable: false
---
## Tone of Voice
- **Friendly but professional** - approachable without being casual
- **Clear and concise** - avoid jargon
- **Confident** - we know what we're doing
- **Empathetic** - understand user needs
## Writing Guidelines
- Use "you" when addressing readers
- Use active voice
- Keep sentences under 20 words
- Start with value proposition
For templates, see [templates/](templates/).示例五：CLAUDE.md 生成技能
yaml
---
name: claude-md
description: Create or update CLAUDE.md files following best practices for optimal AI agent onboarding. Use when users mention CLAUDE.md, project documentation, or AI onboarding.
---
## Core Principles
**LLMs are stateless**: CLAUDE.md is the only file automatically included in every conversation.
### The Golden Rules
1. **Less is More**: Keep under 300 lines (ideally under 100)
2. **Universal Applicability**: Only include information relevant to EVERY session
3. **Don't Use Claude as a Linter**: Use deterministic tools instead
4. **Never Auto-Generate**: Craft it manually with careful consideration
## Essential Sections
- **Project Name**: Brief one-line description
- **Tech Stack**: Primary language, frameworks, database
- **Development Commands**: Install, test, build commands
- **Critical Conventions**: Only non-obvious, high-impact conventions
- **Known Issues / Gotchas**: Things that trip up developers示例六：带脚本的重构技能
目录结构：
refactor/
├── SKILL.md
├── references/
│ ├── code-smells.md
│ └── refactoring-catalog.md
├── templates/
│ └── refactoring-plan.md
└── scripts/
├── analyze-complexity.py
└── detect-smells.py文件： refactor/SKILL.md
yaml
---
name: code-refactor
description: Systematic code refactoring based on Martin Fowler's methodology. Use when users ask to refactor code, improve code structure, reduce technical debt, or eliminate code smells.
---
# Code Refactoring Skill
A phased approach emphasizing safe, incremental changes backed by tests.
## Workflow
Phase 1: Research & Analysis → Phase 2: Test Coverage Assessment →
Phase 3: Code Smell Identification → Phase 4: Refactoring Plan Creation →
Phase 5: Incremental Implementation → Phase 6: Review & Iteration
## Core Principles
1. **Behavior Preservation**: External behavior must remain unchanged
2. **Small Steps**: Make tiny, testable changes
3. **Test-Driven**: Tests are the safety net
4. **Continuous**: Refactoring is ongoing, not a one-time event
For code smell catalog, see [references/code-smells.md](references/code-smells.md).
For refactoring techniques, see [references/refactoring-catalog.md](references/refactoring-catalog.md).支持文件
技能的目录中除 SKILL.md 外还可包含多个文件。这些支持文件（模板、示例、脚本、参考文档）让主技能文件保持精简，同时为 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)）。 - 支持文件在第三级按需加载，因此在 Claude 实际读取之前不会消耗上下文。
管理技能
查看可用技能
直接询问 Claude：
What Skills are available?或检查文件系统：
bash
# 列出个人技能
ls ~/.claude/skills/
# 列出项目技能
ls .claude/skills/测试技能
有两种测试方法：
让 Claude 自动调用，只需提出与描述匹配的问题：
Can you help me review this code for security issues?或直接调用，使用技能名称：
/code-review src/auth/login.ts更新技能
直接编辑 SKILL.md 文件。更改将在下次 Claude Code 启动时生效。
bash
# 个人技能
code ~/.claude/skills/my-skill/SKILL.md
# 项目技能
code .claude/skills/my-skill/SKILL.md限制 Claude 的技能访问
有三种方式控制 Claude 可调用的技能：
在 /permissions 中禁用所有技能：
# 添加到拒绝规则：
Skill允许或拒绝特定技能：
# 仅允许特定技能
Skill(commit)
Skill(review-pr *)
# 拒绝特定技能
Skill(deploy *)通过在前置元数据中添加 disable-model-invocation: true 隐藏单个技能。
最佳实践
1. 使描述具体明确
- 不好（模糊）："帮助处理文档"
- 好（具体）："从 PDF 文件中提取文本和表格，填写表单，合并文档。当处理 PDF 文件或用户提到 PDF、表单或文档提取时使用。"
2. 保持技能专注
- 一个技能 = 一种能力
- 推荐："PDF 表单填写"
- 不推荐："文档处理"（过于宽泛）
3. 包含触发词
在描述中添加与用户请求匹配的关键词：
yaml
description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.4. 将 SKILL.md 保持在 500 行以内
将详细的参考资料移至 Claude 按需加载的独立文件中。
5. 引用支持文件
markdown
## Additional resources
- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)应该做的
- 使用清晰、描述性的名称
- 提供全面的指令
- 添加具体示例
- 打包相关脚本和模板
- 用真实场景测试
- 记录依赖关系
不应该做的
- 不要为一次性任务创建技能
- 不要重复现有功能
- 不要使技能过于宽泛
- 不要省略描述字段
- 不要在未经审计的情况下安装来自不可信来源的技能
故障排除
快速参考
| 问题 | 解决方案 |
|---|---|
| Claude 不使用技能 | 在描述中添加更具体的触发词 |
| 找不到技能文件 | 验证路径：~/.claude/skills/name/SKILL.md |
| YAML 错误 | 检查 --- 标记、缩进，确保没有制表符 |
| 技能冲突 | 在描述中使用不同的触发词 |
| 脚本无法运行 | 检查权限：chmod +x scripts/*.py |
| Claude 看不到所有技能 | 技能数量过多；运行 /context 查看警告 |
技能未触发
如果 Claude 在预期时未使用您的技能：
- 检查描述中是否包含用户自然会说的关键词
- 询问"What skills are available?"验证技能是否出现
- 尝试改变请求措辞以匹配描述
- 使用
/skill-name直接调用进行测试
技能触发过于频繁
如果 Claude 在您不需要时使用了技能：
- 使描述更具体
- 添加
disable-model-invocation: true以改为仅手动调用
Claude 看不到所有技能
技能描述在上下文窗口的 2%（后备值：16,000 个字符）处加载。运行 /context 查看关于被排除技能的警告。可通过 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量覆盖预算。
安全注意事项
只使用来自可信来源的技能。 技能通过指令和代码为 Claude 提供能力——恶意技能可以指示 Claude 以有害方式调用工具或执行代码。
关键安全注意事项：
- 彻底审计：检查技能目录中的所有文件
- 外部来源存在风险：从外部 URL 获取内容的技能可能被篡改
- 工具滥用：恶意技能可以以有害方式调用工具
- 视同安装软件：只使用来自可信来源的技能
技能与其他功能的对比
| 功能 | 调用方式 | 适用场景 |
|---|---|---|
| 技能 | 自动或 /name | 可复用的专业知识、工作流 |
| 斜杠命令 | 用户发起 /name | 快捷方式（已合并到技能中） |
| 子代理 | 自动委托 | 隔离的任务执行 |
| 记忆（CLAUDE.md） | 始终加载 | 持久的项目上下文 |
| MCP | 实时 | 外部数据/服务访问 |
| 钩子 | 事件驱动 | 自动化副作用 |
内置技能
Claude Code 附带了几个始终可用的内置技能，无需安装：
| 技能 | 描述 |
|---|---|
/simplify | 审查已更改的文件以提高复用性、质量和效率；生成 3 个并行审查代理 |
/batch <instruction> | 使用 git worktrees 跨代码库编排大规模并行更改 |
/debug [description] | 通过读取调试日志排查当前会话问题 |
/loop [interval] <prompt> | 按间隔重复运行提示（例如 /loop 5m check the deploy） |
/claude-api | 加载 Claude API/SDK 参考；在导入 anthropic/@anthropic-ai/sdk 时自动激活 |
这些技能开箱即用，无需安装或配置。它们遵循与自定义技能相同的 SKILL.md 格式。
共享技能
项目技能（团队共享）
- 在
.claude/skills/中创建技能 - 提交到 git
- 团队成员拉取变更——技能立即可用
个人技能
bash
# 复制到个人目录
cp -r my-skill ~/.claude/skills/
# 赋予脚本可执行权限
chmod +x ~/.claude/skills/my-skill/scripts/*.py插件分发
将技能打包在插件的 skills/ 目录中以进行更广泛的分发。
进阶：技能集合与技能管理器
一旦您开始认真构建技能，有两件事变得不可或缺：一个经过验证的技能库和一个管理它们的工具。
luongnv89/skills — 我在几乎所有项目中每天使用的技能集合。亮点包括 logo-designer（即时生成项目 logo）和 ollama-optimizer（为您的硬件调优本地 LLM 性能）。如果您想要开箱即用的技能，这是一个很好的起点。
luongnv89/asm — 代理技能管理器（Agent Skill Manager）。处理技能开发、重复检测和测试。asm link 命令允许您在任何项目中测试技能而无需复制文件——当您拥有超过少量技能时，这是必不可少的。