Agent Skill 介绍
Agent Skill 是一种让 AI 助手获得特定能力的开放标准。它将 AI 的能力从临时的"提示词"升级为永久、可复用、可共享的技能模块，就像给 AI 安装"插件"一样，让它能够专业地处理特定类型的任务。
本文档基于 Agent Skills 开放标准 和 Anthropic 官方指南编写。
什么是 Agent Skill？
Agent Skill（智能体技能）本质上是一个包含指令文件的文件夹，用于教会 AI 如何处理特定任务或工作流程。它的核心理念是：一次编写，到处运行。
传统方式 vs Agent Skill
在没有 Agent Skill 之前，每次需要 AI 执行特定任务时，你都需要：
用户：请帮我写一个 Python 函数，要求：
1. 使用类型注解
2. 包含文档字符串
3. 遵循 PEP 8 规范
4. 添加单元测试
...（每次都要重复这些要求）
有了 Agent Skill 之后：
用户：请用 python-best-practices skill 写一个排序函数
AI：（自动应用预定义的规范，输出符合要求的代码）
Agent Skill 解决的问题
| 问题 | 传统方式 | Agent Skill 方式 |
|---|---|---|
| 重复说明 | 每次都要详细描述需求 | 一次定义，多次复用 |
| 一致性 | 不同对话可能产生不同风格 | 统一的输出标准 |
| 知识沉淀 | 难以积累最佳实践 | 可打包分享的专业技能 |
| Token 消耗 | 每次都要发送完整指令 | 按需加载，节省成本 |
Agent Skill 与其他技术的关系
与 MCP 的对比
Agent Skill 和 MCP（Model Context Protocol）都是开放标准，但它们解决不同层面的问题：
| 特性 | Agent Skill | MCP |
|---|---|---|
| 核心功能 | 教 AI 如何执行任务 | 让 AI 访问外部资源 |
| 侧重点 | 知识和工作流程 | 数据源和工具连接 |
| 内容形式 | Markdown 指令文件 | JSON-RPC 协议服务 |
| 使用场景 | 代码审查、文档生成、测试编写 | 数据库查询、API 调用、文件系统访问 |
| 类比 | 提供"脑"（专业知识） | 提供"手"（访问能力） |
何时使用 Agent Skill？
- 你想让 AI 遵循特定的工作流程
- 你需要封装团队的最佳实践
- 你希望 AI 在特定领域表现得更专业
- 你想复用和分享专业知识
何时使用 MCP？
- 你需要连接数据库、API 或文件系统
- 你想让 AI 访问实时数据
- 你需要执行系统命令或调用外部服务
- 你要集成现有的工具链
协同工作
两者可以协同使用：MCP 提供数据和工具访问能力，Agent Skill 提供专业知识指导。例如：
- MCP 连接数据库 → Agent Skill 指导数据分析 → 输出专业报告
- MCP 访问代码仓库 → Agent Skill 执行代码审查 → 生成审查报告
- MCP 调用 CI/CD API → Agent Skill 编写部署流程 → 执行部署
与 CLAUDE.md 的区别
CLAUDE.md 是项目级上下文文件，包含项目特定的约定和知识。它与 Agent Skill 的区别：
| 特性 | CLAUDE.md | Agent Skill |
|---|---|---|
| 作用范围 | 单个项目 | 可跨项目复用 |
| 加载方式 | 始终加载 | 按需激活 |
| 适用场景 | 项目约定、编码规范 | 可复用的工作流程 |
| 分发方式 | 提交到代码仓库 | 可独立分发和共享 |
如何选择使用哪个？
-
使用 CLAUDE.md 当你需要：定义项目特定的编码规范、说明项目结构、记录团队约定。这些内容在项目的每次对话中都需要被知道。
-
使用 Agent Skill 当你需要：封装可复用的工作流程、创建可以在多个项目中使用的专业技能、分享给团队或社区的专业知识。
协同使用示例：
CLAUDE.md 内容：
- 本项目使用 Python 3.11
- 数据库连接配置在 config/database.py
- API 密钥存储在环境变量中
Agent Skill (python-code-reviewer) 内容：
- 如何进行专业的代码审查
- 检查清单和最佳实践
- 输出格式规范
CLAUDE.md 提供项目上下文，Skill 提供专业知识，两者配合使用效果最佳。
与 Subagents 的关系
Subagents（子代理）是独立运行的代理实例，可以执行特定任务。Agent Skill 可以配置为在子代理中运行：
- 内联执行：Skill 内容直接注入到当前对话
- 子代理执行：Skill 在隔离的子代理中运行，完成后返回结果
子代理执行适合需要隔离上下文的复杂任务，如大规模代码分析、长时间运行的批处理等。
核心特性
1. 开放标准
2025 年 12 月，Anthropic 将 Agent Skills 发布为开放标准，这意味着：
- 跨平台兼容：同一个 Skill 可以在 Claude Code、OpenAI Codex、Cursor、Gemini CLI 等多种工具中使用
- 社区共享：开发者可以创建和分享自己的 Skills
- 标准化格式：遵循统一的规范，确保互操作性
- GitHub 生态：官方维护 skills-ref 验证库和示例 Skills 仓库
2. 按需加载
Skills 只在真正需要时才会被调用，这带来两个好处：
- 节省 Token：不会在每次对话中都加载所有指令
- 精准触发：通过 description 字段精确控制触发时机
3. 可组合性
多个 Skills 可以协同工作，构建复杂的工作流：
Skill 1: 代码格式化 → Skill 2: 语法检查 → Skill 3: 单元测试生成
核心价值
Agent Skills 的核心价值在于将 AI 的能力从"临时提示"升级为"可复用的专业技能"。
为什么需要 Skills？
当你与 AI 助手协作时，可能会遇到这些问题：
问题一：重复说明
每次都要详细描述你的需求："请用 Python 写一个函数，要有类型注解，要有文档字符串，要遵循 PEP 8 规范..." 这些重复的说明消耗时间和精力。
问题二：不一致的输出
同一个任务，不同对话可能产生不同风格的输出。今天 AI 用 Google 风格的 docstring，明天可能用 NumPy 风格。
问题三：知识难以积累
你发现 AI 在某个任务上表现出色，总结了一套方法，但下次对话又要重新教它。
问题四：难以分享最佳实践
你的团队有一套编码规范，但很难让每个成员在与 AI 协作时都保持一致。
Agent Skills 解决了这些问题：一次定义，处处复用。你把专业知识写进 SKILL.md，AI 就能在需要时自动应用。
Skills 的核心特性
自描述性：SKILL.md 文件本身就可读，任何人都能理解这个 Skill 做什么。这使得 Skills 易于审计、改进和维护。
可扩展性：从简单的文本指令到包含脚本、模板、参考文档的复杂技能包，Skills 可以根据需求灵活扩展。
可移植性：Skills 只是文件，所以容易编辑、版本控制、分享。一个在 Claude Code 中创建的 Skill 可以直接在 OpenAI Codex、Cursor、Windsurf 等工具中使用。
应用场景
软件开发
- 代码审查：自动检查代码质量、安全漏洞
- 文档生成：按照团队规范生成 API 文档
- 测试编写：自动生成单元测试和集成测试
内容创作
- 技术写作：遵循特定风格指南
- 翻译校对：保持术语一致性
- SEO 优化：检查关键词密度和结构
数据分析
- 报告生成：统一的数据可视化风格
- 代码规范：确保分析脚本的可维护性
- 结果解读：专业的数据解读框架
DevOps
- CI/CD 配置：标准化的流水线模板
- 监控告警：规范的告警规则编写
- 日志分析：统一的日志解析方法
快速预览
一个最简单的 Skill 结构如下：
my-skill/
└── SKILL.md
SKILL.md 文件内容：
---
name: "code-reviewer"
description: "审查代码质量、发现潜在问题。当用户请求代码审查或提交代码时触发。"
---
# 代码审查专家
你是一位专业的代码审查员。在审查代码时，请关注：
## 审查范围
1. **代码质量**：检查命名规范、代码结构
2. **潜在问题**：发现可能的 bug 和安全隐患
3. **性能优化**：识别性能瓶颈
4. **最佳实践**：提供改进建议
## 输出格式
- 问题列表（按严重程度排序）
- 具体改进建议
- 总体评价
这就是创建一个 Skill 所需的全部内容。安装后，AI 会根据 description 自动判断何时使用这个 Skill。
渐进式披露机制
Agent Skills 采用渐进式披露（Progressive Disclosure）策略来高效管理上下文，这是其核心设计理念之一。
三层加载机制
| 层级 | 加载内容 | 加载时机 | Token 消耗 |
|---|---|---|---|
| 1. 元数据 | name + description | 会话启动时，加载所有 Skills | 每个 Skill 约 50-100 tokens |
| 2. 指令 | 完整 SKILL.md 正文 | Skill 被激活时 | 建议 < 5000 tokens |
| 3. 资源 | scripts、references、assets | 指令明确引用时 | 按需加载 |
为什么这样设计？
传统方式需要在每次对话中都包含完整的指令，导致大量 Token 浪费。渐进式披露让 Agent 只在真正需要时才加载完整内容：
- 会话启动：只加载所有 Skill 的 name 和 description，建立"技能目录"
- 任务匹配：当用户任务与某个 Skill 的 description 匹配时，才激活该 Skill
- 按需深入：只有当指令明确引用
scripts/或references/中的文件时，才加载这些资源
这种设计使得即使安装了数十个 Skills，也不会显著影响初始上下文大小。
发展历程
Agent Skills 格式最初由 Anthropic 开发，随后发布为开放标准，并被越来越多的 AI 编程工具采用。
| 里程碑 | 说明 |
|---|---|
| 标准创立 | Anthropic 开发并发布 Agent Skills 开放标准 |
| 官方规范 | agentskills.io 成为官方规范网站 |
| 广泛采用 | Claude Code、OpenAI Codex、Cursor、Windsurf、Gemini CLI 等主流工具支持 |
| 生态发展 | 社区涌现大量共享 Skills，形成跨平台生态 |
Agent Skills 是真正的开放标准，任何 AI 工具都可以实现支持。规范完全公开在 agentskills.io，包含完整的格式定义、最佳实践和客户端实现指南。
学习路径
本教程将带你从零开始掌握 Agent Skill：
- 文件结构：了解 Skill 的组成部分和规范要求
- 编写 Skills：学习如何创建高质量的 Skill
- 最佳实践：掌握 Skill 设计的核心原则
- 实战案例：通过真实案例加深理解
- 工具支持：了解各平台的使用方法
- 评估质量：系统化评估和优化 Skill
- 调试技巧：解决常见问题和优化 Skill
准备好开始了吗？让我们从 文件结构 开始。