代理技能（Agent Skill）指南

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

概述

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

核心优势

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

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

注意：自定义斜杠命令（Slash Command）已合并到技能中。.claude/commands/ 文件仍然有效，并支持相同的前置元数据（Frontmatter）字段。新开发推荐使用技能。当两者在同一路径下存在时（如 .claude/commands/review.md 和 .claude/skills/review/SKILL.md），技能优先。

技能工作原理：渐进式展示（Progressive Disclosure）

技能利用渐进式展示架构——Claude 按需分阶段加载信息，而非预先消耗上下文。这使得上下文管理高效的同时保持无限的可扩展性。

三个加载级别

graph TB
    subgraph "级别 1：元数据（始终加载）"
        A["YAML 前置元数据"]
        A1["每个技能约 100 个令牌"]
        A2["name + description"]
    end

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

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

    A --> B
    B --> C

级别	何时加载	令牌消耗	内容
级别 1：元数据	始终（启动时）	每个技能约 100 令牌	YAML 前置元数据中的 name 和 description
级别 2：指令	技能被触发时	低于 5k 令牌	SKILL.md 正文中的指令和指导
级别 3+：资源	按需	实际上无限制	通过 bash 执行的捆绑文件，不将内容加载到上下文中

这意味着你可以安装许多技能而无上下文惩罚——Claude 只知道每个技能的存在和使用时机，直到真正触发。

技能加载过程

sequenceDiagram
    participant User as 用户
    participant Claude as Claude
    participant System as 系统
    participant Skill as 技能

    User->>Claude: "审查这段代码的安全问题"
    Claude->>System: 检查可用技能（元数据）
    System-->>Claude: 技能描述在启动时已加载
    Claude->>Claude: 匹配请求到技能描述
    Claude->>Skill: bash: read code-review/SKILL.md
    Skill-->>Claude: 指令加载到上下文
    Claude->>Claude: 判断：需要模板吗？
    Claude->>Skill: bash: read templates/checklist.md
    Skill-->>Claude: 模板已加载
    Claude->>Claude: 执行技能指令
    Claude->>User: 全面的代码审查