Agent Skills

Anthropic 推出的开放标准，让 AI Agent 以模块化方式扩展能力——一次编写，随处部署。

核心概念 Link to heading

为什么需要 Agent Skills Link to heading

MCP（Model Context Protocol）解决了 Agent 如何接入外部工具的问题，但它不负责定义"Agent 本身应该具备什么能力"。Agent Skills 填补了这一空白：它将特定领域的知识、工作流和最佳实践打包成可复用的模块，使通用 Agent 能够快速转变为专业角色。

打个比方：MCP 是 Agent 的 USB 接口，Agent Skills 是 Agent 的职业资格证书。

Agent Skills 架构

SKILL.md：技能的核心载体 Link to heading

SKILL.md 结构

一个 Skill 本质上是一个包含 SKILL.md 文件的目录。SKILL.md 由 YAML frontmatter 和 Markdown 正文组成：

---
name: code-reviewer
description: 对代码变更进行结构化审查，关注安全性、可维护性和潜在 bug
tags:
  - review
  - quality
---

# Code Reviewer

## When to use this skill
当用户提交代码变更、发起 Pull Request、或要求进行代码质量检查时使用。

## Instructions
1. 检查安全问题（注入、路径遍历、硬编码凭据）
2. 评估可维护性（函数长度、命名、重复代码）
3. 验证测试覆盖率
4. 输出结构化审查报告

注：SKILL.md 的正文标题（如 When to use this skill、Instructions）是行业惯例使用的英文标识，实际编写时也可用中文。

关键字段说明：

name：kebab-case 格式，最长 64 字符
description：必须是单行，这是 Agent 决定是否加载该技能的触发条件——写给模型看，不是给人看的
tags：用于分类和过滤

Progressive Disclosure：渐进式上下文加载 Link to heading

这是 Agent Skills 架构的核心创新。

Progressive Disclosure 等级图

传统做法需要在 system prompt 中一次性注入所有指令，导致 context window 被大量占用。Progressive Disclosure 机制的工作流程是：

Agent 启动时只加载所有 Skill 的 name + description（极少量 token）
用户输入任务后，Agent 根据 description 判断需要哪些 Skill
仅加载被选中的 Skill 的完整内容，其余 Skill 保持未加载状态

flowchart LR A[Agent 启动] --> B[加载所有 SKILL.md 的 name+description] B --> C[用户输入任务] C --> D{匹配 description} D -->|匹配| E[加载 Skill 完整内容] D -->|不匹配| F[保持未加载] E --> G[按 Skill 指令执行]

这意味着你可以安装几十个甚至上百个 Skill，而不会产生显著的上下文开销——只有当前任务相关的 Skill 才会被激活。

Skill 生命周期 Link to heading

Skill 生命周期图

一个 Skill 从安装到执行经历三个阶段：

发现：Agent 扫描指定目录（如 .claude/skills/），读取所有 SKILL.md 的 name 和 description
匹配：用户输入任务时，Agent 比对 description，决定激活哪些 Skill
执行：加载匹配的 Skill 全文，按其中的指令、脚本和引用资源执行

项目结构与集成 Link to heading

目录结构 Link to heading

一个完整的 Skill 目录结构如下：

.claude/
└── skills/
    └── code-reviewer/
        ├── SKILL.md          # 指令和规则定义（必须）
        ├── references/       # 参考文档（可选）
        │   └── checklist.md  # 审查检查清单
        └── scripts/          # 辅助脚本（可选）
            └── lint.sh       # 自动 lint 脚本

SKILL.md：核心文件，包含触发条件和执行指令
references/：大型参考文档拆分到此处，通过 progressive disclosure 按需加载
scripts/：可执行脚本，Agent 可在执行过程中调用

与 Claude Code 集成 Link to heading

将 Skill 目录放入项目的 .claude/skills/ 目录即可。Claude Code 启动时自动扫描，用户输入任务时自动匹配加载——无需额外配置。

与 Claude API 集成 Link to heading

通过 API 调用时，将 SKILL.md 的 name、description 和正文作为 tool 参数传入，Claude 即可按照 Skill 定义的指令执行：

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    tools=[
        {
            "type": "skill",
            "name": "code-reviewer",
            "description": "对代码变更进行结构化审查",
            "input_schema": {...}
        }
    ],
    messages=[{"role": "user", "content": "请审查这段代码..."}]
)

实际使用 Link to heading

场景：创建代码审查 Skill Link to heading

假设团队需要标准化的代码审查流程：

1. 创建目录

mkdir -p .claude/skills/code-reviewer

2. 编写 SKILL.md

SKILL.md 的正文是执行指令。以代码审查为例，核心是定义检查清单和输出格式：

# Code Reviewer

## When to use this skill

当用户要求审查代码、检查 PR、或分析代码质量时激活。

## Review Checklist

- [ ] 是否存在注入漏洞（SQL、XSS、命令注入）
- [ ] 是否有硬编码的凭据或密钥
- [ ] 错误处理是否覆盖异常路径
- [ ] 函数是否超过 50 行（建议拆分）
- [ ] 命名是否清晰表达意图

## Output Format

按以下格式输出审查结果：

1. **安全**：🟢 无风险 / 🔴 发现问题
2. **可维护性**：评分 1-5
3. **建议**：具体改进意见