返回笔记列表

Agent Skills：AI Agent 能力扩展的开放标准深度解析

|预计阅读 5 分钟
AI编程Agent SkillsClaude Code开放标准

Agent Skills：AI Agent 能力扩展的开放标准深度解析

随着 AI Agent 的快速发展，一个关键问题日益凸显：如何让 Agent 获得特定领域的专业知识和能力？ Agent Skills 应运而生，它是一个轻量级、开放的格式标准，旨在解决 AI Agent 能力扩展的痛点。

什么是 Agent Skills？

Agent Skills 是一个开放的格式标准，用于给 AI Agent 提供新能力和专业知识。它的核心理念是：将专业知识打包成可复用的技能包，让 Agent 按需加载使用。

核心价值

价值 描述
领域专业知识 打包专业知识为可复用指令
新能力扩展 给 Agent 新能力（创建演示文稿、构建 MCP 服务器等）
可重复工作流 将多步骤任务转化为一致、可审计的工作流
互操作性 同一 skill 可跨不同 Agent 产品使用

支持的 Agent 产品

Agent Skills 已被 30+ 主流 AI 开发工具采纳：

  • Claude Code - Anthropic 的终端编程助手
  • Cursor - AI 代码编辑器
  • GitHub Copilot - GitHub 的 AI 编程助手
  • OpenAI Codex - OpenAI 的编程 Agent
  • Gemini CLI - Google 的终端 AI 助手
  • VS Code - 微软的代码编辑器
  • OpenHands - 开源云编程 Agent
  • Goose - Block 的开源 AI Agent

技术架构

目录结构

一个 Skill 本质上是一个文件夹，包含必要的元数据和指令：

my-skill/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行代码
├── references/       # 可选：参考文档
└── assets/           # 可选：模板、资源文件

SKILL.md 格式

SKILL.md 是 Skill 的核心文件，采用 YAML frontmatter + Markdown 格式：

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
compatibility: Requires Python 3.10+
metadata:
  author: example-org
  version: "1.0"
---

# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files...

## How to extract text
1. Use pdfplumber for text extraction...

## How to fill forms
...

Frontmatter 字段规范

字段 必需 约束
name 是 1-64 字符，小写字母、数字、连字符，不能以连字符开头或结尾
description 是 1-1024 字符，描述功能和使用场景
license 否 许可证名称或引用
compatibility 否 环境要求说明
metadata 否 任意键值对元数据
allowed-tools 否 预批准的工具列表（实验性）

渐进式披露机制

Agent Skills 采用**渐进式披露（Progressive Disclosure）**机制，高效管理上下文：

┌─────────────────────────────────────────────────────────┐
│  阶段 1：发现 (Discovery)                                │
│  ─────────────────────────────────────────────────────  │
│  启动时仅加载 name + description (~100 tokens)          │
│  Agent 知道何时可能需要这个 skill                        │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│  阶段 2：激活 (Activation)                               │
│  ─────────────────────────────────────────────────────  │
│  任务匹配时，加载完整 SKILL.md (< 5000 tokens 推荐)      │
│  Agent 获得详细指令                                      │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│  阶段 3：执行 (Execution)                                │
│  ─────────────────────────────────────────────────────  │
│  按需加载 scripts/、references/、assets/ 中的资源        │
│  Agent 执行具体任务                                      │
└─────────────────────────────────────────────────────────┘

上下文管理建议

  • SKILL.md 主体：建议控制在 500 行以内
  • 详细参考材料：移至 references/ 目录
  • 脚本代码：放在 scripts/ 目录
  • 静态资源：放在 assets/ 目录

实战示例

示例 1：代码审查 Skill

code-review/
├── SKILL.md
├── scripts/
│   └── analyze.py
└── references/
    └── CHECKLIST.md

SKILL.md:

---
name: code-review
description: Perform comprehensive code review for security, performance, and best practices. Use when reviewing PRs or code changes.
---

# Code Review Skill

## When to use
- Reviewing pull requests
- Analyzing code changes
- Security audits

## Review checklist

### Security
- [ ] Input validation
- [ ] SQL injection prevention
- [ ] XSS prevention
- [ ] Authentication checks

### Performance
- [ ] N+1 query detection
- [ ] Memory leak checks
- [ ] Algorithm complexity

### Best Practices
- [ ] Code style consistency
- [ ] Documentation
- [ ] Test coverage

## Scripts
Run `scripts/analyze.py` for automated analysis.

## References
See [CHECKLIST.md](references/CHECKLIST.md) for detailed checklist.

示例 2：API 文档生成 Skill

api-docs/
├── SKILL.md
├── scripts/
│   ├── openapi-gen.py
│   └── validate.py
├── references/
│   └── OPENAPI_SPEC.md
└── assets/
    └── template.yaml

SKILL.md:

---
name: api-docs
description: Generate OpenAPI documentation from code annotations. Use when creating or updating API documentation.
compatibility: Requires Python 3.10+ and OpenAPI 3.0
---

# API Documentation Generator

## Overview
Automatically generate OpenAPI 3.0 documentation from code annotations.

## Usage

### 1. Annotate your endpoints
```python
@app.get("/users/{user_id}")
@doc(summary="Get user by ID", response_model=UserResponse)
async def get_user(user_id: int):
    ...

2. Generate documentation

python scripts/openapi-gen.py ./src --output ./docs/openapi.yaml

3. Validate output

python scripts/validate.py ./docs/openapi.yaml

Template

See assets/template.yaml for customization options.


## 与其他方案的对比

| 特性 | Agent Skills | CLAUDE.md | MCP | 传统插件 |
|------|-------------|-----------|-----|----------|
| **格式** | 开放标准 | 项目特定 | 协议标准 | 各自定义 |
| **跨平台** | ✅ 30+ 工具 | ❌ 仅 Claude Code | ✅ 多工具 | ❌ 单一工具 |
| **按需加载** | ✅ 渐进式 | ❌ 全量加载 | ✅ 动态调用 | 取决于实现 |
| **可移植性** | ✅ 文件夹 | ✅ 文件 | ⚠️ 需配置 | ❌ 依赖安装 |
| **适用场景** | 可复用能力 | 项目指令 | 外部工具集成 | 深度定制 |

## 最佳实践

### 编写高质量 description

**好的示例**：
```yaml
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

不好的示例：

description: Helps with PDFs.

组织 Skill 结构

✅ 推荐：
skill-name/
├── SKILL.md          # 简洁的核心指令
├── references/
│   ├── advanced.md   # 高级用法
│   └── examples.md   # 示例
└── scripts/
    └── main.py

❌ 避免：
skill-name/
├── SKILL.md          # 超过 500 行
├── deep/
│   └── nested/
│       └── structure/  # 过深的目录结构

文件引用

使用相对路径，保持一层深度：

✅ 推荐：
See [reference guide](references/REFERENCE.md) for details.

❌ 避免：
See [guide](references/advanced/topics/deep/nested.md) for details.

验证工具

使用官方的 skills-ref 库验证 Skill：

# 安装
pip install skills-ref

# 验证
skills-ref validate ./my-skill

开放生态

Agent Skills 由 Anthropic 开发并作为开放标准发布，在 GitHub 上开源：

总结

Agent Skills 解决了 AI Agent 能力扩展的核心痛点：

  1. 标准化：统一的格式规范，降低学习成本
  2. 可移植：一次编写，多平台复用
  3. 高效：渐进式加载，节省上下文
  4. 开放：社区驱动，持续演进

对于开发者而言，掌握 Agent Skills 意味着：

  • 可以将自己的专业知识打包成可复用的技能
  • 可以在多个 AI 工具中复用同一套技能
  • 可以为团队或企业创建专属的能力库

随着 AI Agent 的普及，Agent Skills 有望成为 AI 能力扩展的事实标准。

参考资料

更新日期：2026-05-16

评论