Agent Skills：赋予 AI Agent 专业能力的开放标准

陈暖秋
31 阅读9分钟

一种简单、开放的格式，让 AI Agent 获得新能力和专业知识

什么是 Agent Skills？

Agent Skills 是一种轻量级、开放的格式，用于扩展 AI Agent 的能力，使其具备专业知识和特定工作流程。

简单来说，Agent Skills 是包含指令、脚本和资源的文件夹，Agent 可以发现并使用这些资源来更准确、更高效地完成任务。

核心定义：Agent Skills 是包含 SKILL.md 文件的文件夹，该文件包含元数据（至少包括名称和描述）以及告诉 Agent 如何执行特定任务的指令。Skills 还可以捆绑脚本、模板和参考材料。

为什么需要 Agent Skills？

随着 AI Agent 能力的不断增强，它们往往缺乏执行实际工作所需的上下文信息。Agent Skills 通过以下方式解决这个问题：

特性说明
领域专业知识将法律审查流程、数据分析管道等专业领域知识打包成可重用的指令
新能力扩展赋予 Agent 新能力，如创建演示文稿、构建 MCP 服务器、分析数据集等
可重复工作流将多步骤任务转化为一致且可审计的工作流程，确保每次执行的质量
互操作性在不同的 Skills 兼容 Agent 产品中重用相同的 Skill，避免重复开发

谁可以从 Agent Skills 中受益？

  • Skill 作者：一次构建能力，部署到多个 Agent 产品中
  • 兼容 Agent：支持 Skills 让终端用户能够开箱即用地赋予 Agent 新能力
  • 团队和企业：将组织知识捕获到可移植、版本控制的包中

Agent Skills 的工作原理

Agent Skills 使用**渐进式披露（Progressive Disclosure）**来高效管理上下文：

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   1. 发现    │  →   │   2. 激活    │  →   │   3. 执行    │
├─────────────┤      ├─────────────┤      ├─────────────┤
│ 启动时，Agent │      │ 当任务与 Skill │      │ Agent 遵循指令，│
│ 仅加载每个可用 │      │ 描述匹配时，   │      │ 按需加载引用文件 │
│ Skill 的名称和 │      │ Agent 读取完整 │      │ 或执行捆绑代码  │
│ 描述        │      │ SKILL.md 指令 │      │              │
└─────────────┘      └─────────────┘      └─────────────┘

这种方法既保持了 Agent 的快速响应，又使其能够按需访问更多上下文信息。

SKILL.md 文件格式

每个 Skill 都必须包含一个 SKILL.md 文件，该文件包含 YAML 前置元数据和 Markdown 内容。

目录结构

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

前置元数据字段

字段必需约束条件
name是最多 64 字符，小写字母、数字和连字符，不能以连字符开头或结尾
description是最多 1024 字符，描述 Skill 的功能和使用时机
license否许可证名称或捆绑许可证文件的引用
compatibility否最多 500 字符，指示环境要求
metadata否任意键值映射，用于附加元数据
allowed-tools否Skill 可使用的预批准工具列表（实验性）

完整示例

---
name: pdf-processing
description: 从 PDF 文件中提取文本和表格，填写表单，合并文档。
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

# PDF 处理

## 何时使用此 Skill
当用户需要处理 PDF 文件时使用此 Skill...

## 如何提取文本
1. 使用 pdfplumber 进行文本提取...

## 如何填写表单
...

各字段详细说明

name 字段

约束条件：

  • 必须是 1-64 个字符
  • 只能包含小写字母、数字和连字符（a-z 和 -）
  • 不能以 - 开头或结尾
  • 不能包含连续的连字符（--）
  • 必须与父目录名称匹配

有效示例：

name: pdf-processing
name: data-analysis
name: code-review

无效示例：

name: PDF-Processing    # 不允许大写
name: -pdf              # 不能以连字符开头
name: pdf--processing   # 不允许连续连字符

description 字段

约束条件：

  • 必须是 1-1024 个字符
  • 应该描述 Skill 的功能和使用时机
  • 应包含帮助 Agent 识别相关任务的关键词

好的示例：

description: 从 PDF 文件中提取文本和表格，填写 PDF 表单，并合并多个 PDF。在处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。

差的示例：

description: 帮助处理 PDF。

license 字段（可选）

指定应用于 Skill 的许可证。建议保持简短（许可证名称或捆绑许可证文件的名称）。

license: Proprietary. LICENSE.txt has complete terms

compatibility 字段（可选）

指示环境要求，如目标产品、所需系统包、网络访问需求等。

compatibility: Designed for Claude Code (or similar products)
compatibility: Requires git, docker, jq, and access to the internet

metadata 字段（可选）

字符串键到字符串值的映射，客户端可用于存储代理技能规范未定义的其他属性。

metadata:
  author: example-org
  version: "1.0"

allowed-tools 字段（可选）

预批准运行的工具的空格分隔列表。实验性功能，不同 Agent 实现对该字段的支持可能有所不同。

allowed-tools: Bash(git:*) Bash(jq:*) Read

可选目录详解

scripts/

包含 Agent 可以运行的可执行代码。脚本应该：

  • 自包含或清晰记录依赖项
  • 包含有用的错误消息
  • 优雅地处理边缘情况

支持的语言取决于 Agent 实现。常见选项包括 Python、Bash 和 JavaScript。

references/

包含 Agent 可以按需读取的附加文档：

  • REFERENCE.md - 详细技术参考
  • FORMS.md - 表单模板或结构化数据格式
  • 领域特定文件（finance.md、legal.md 等）

保持单个参考文件聚焦。Agent 按需加载这些文件，因此较小的文件意味着更少的上下文使用。

assets/

包含静态资源：

  • 模板（文档模板、配置模板）
  • 图像（图表、示例）
  • 数据文件（查找表、模式）

渐进式披露最佳实践

Skills 应该为高效使用上下文而构建：

层级内容大小
元数据name 和 description 字段~100 tokens
指令完整的 SKILL.md 正文< 5000 tokens（推荐）
资源scripts/、references/ 或 assets/ 中的文件按需加载

保持主 SKILL.md 在 500 行以下。将详细参考材料移到单独的文件中。

如何将 Skills 集成到你的 Agent

有两种主要的集成方法：

基于文件系统的 Agent

在计算机环境（bash/unix）中运行的 Agent，当模型发出 shell 命令（如 cat /path/to/my-skill/SKILL.md）时激活 Skills。捆绑的资源通过 shell 命令访问。

基于工具的 Agent

在没有专用计算机环境的情况下运行。相反，它们实现允许模型触发 Skills 和访问捆绑资源的工具。具体的工具实现由开发者决定。

集成步骤

一个兼容 Skills 的 Agent 需要：

  1. 发现：在配置的目录中发现 Skills
  2. 加载元数据：启动时仅加载名称和描述
  3. 匹配：将用户任务与相关 Skills 匹配
  4. 激活：通过加载完整指令来激活 Skills
  5. 执行：按需执行脚本和访问资源

Skill 发现代码示例

function parseMetadata(skillPath):
    content = readFile(skillPath + "/SKILL.md")
    frontmatter = extractYAMLFrontmatter(content)
    return {
        name: frontmatter.name,
        description: frontmatter.description,
        path: skillPath
    }

系统提示格式

将 Skill 元数据包含在系统提示中，以便模型知道有哪些 Skills 可用。对于 Claude 模型，推荐格式使用 XML：

<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>从 PDF 文件中提取文本和表格，填写表单，合并文档。</description>
    <location>/path/to/skills/pdf-processing/SKILL.md</location>
  </skill>
  <skill>
    <name>data-analysis</name>
    <description>分析数据集，生成图表，创建摘要报告。</description>
    <location>/path/to/skills/data-analysis/SKILL.md</location>
  </skill>
</available_skills>

对于基于文件系统的 Agent，包含带有 SKILL.md 文件绝对路径的 location 字段。对于基于工具的 Agent，可以省略 location。

保持元数据简洁。每个 Skill 应该向上下文添加大约 50-100 个 tokens。

实际应用场景

1. PDF 处理 Skill

自动从 PDF 文件中提取文本、表格，填写表单，合并多个文档。适用于：

  • 法律文档处理
  • 财务报表分析
  • 合同审查

2. 数据分析 Skill

分析数据集，生成可视化图表，创建摘要报告。适用于：

  • 业务数据分析
  • 市场研究
  • 运营报告

3. 代码审查 Skill

提供代码审查流程、最佳实践检查清单、安全问题检测等专业能力。适用于：

  • 软件开发
  • DevOps 流程
  • 安全审计

4. 演示文稿创建 Skill

根据内容自动生成专业的演示文稿，包括幻灯片设计、内容排版等。适用于：

  • 商务汇报
  • 教育培训
  • 产品展示

安全考虑

脚本执行引入了安全风险，建议采取以下措施：

措施说明
沙箱化在隔离环境中运行脚本，限制其对系统的访问权限
白名单仅执行来自受信任 Skills 的脚本，避免运行未知来源的代码
确认机制在执行潜在危险操作前询问用户确认，增加人工审核环节
日志记录记录所有脚本执行以供审计，便于追踪和排查问题

验证 Skills

使用 skills-ref 参考库验证你的 Skills：

skills-ref validate ./my-skill

这将检查你的 SKILL.md 前置元数据是否有效并遵循所有命名约定。

参考实现库

skills-ref 库提供了用于处理 Skills 的 Python 工具和 CLI：

  • 验证 Skill 目录：skills-ref validate <path>
  • 生成系统提示 XML：skills-ref to-prompt <path>...

使用库源代码作为参考实现。

开始使用 Agent Skills

Agent Skills 格式最初由 Anthropic 开发，作为开放标准发布，并已被越来越多的 Agent 产品采用。该标准开放接受更广泛生态系统的贡献。

资源链接

总结

Agent Skills 是 AI Agent 生态系统的开放标准，让每个人都能为 AI 赋予专业能力。通过简单的文件夹结构和 YAML + Markdown 格式，开发者和企业可以：

  1. 创建可重用的专业能力模块
  2. 在不同 Agent 产品间共享 Skills
  3. 将组织知识版本化和可移植化
  4. 让 AI Agent 更准确地完成专业任务

无论你是 Skill 作者、Agent 开发者还是企业用户，Agent Skills 都为你提供了一种标准化的方式来扩展 AI 的能力边界。

本文内容基于 agentskills.io 官方文档整理

avatar
文章
阅读
粉丝