返回博客列表
AI开发

Agent Skills规范详解：构建AI技能的标准格式

深入解析Agent Skills规范，学习如何创建符合标准的AI技能，包括目录结构、SKILL.md格式、最佳实践等

2026-04-01
10 分钟 阅读

Agent Skills规范详解：构建AI技能的标准格式

引言

Agent Skills是AI助手技能的标准格式规范，它为AI助手（如OpenClaw）提供了一种统一的方式来定义、发现和使用技能。本文将详细介绍Agent Skills规范的核心内容，帮助你理解如何创建符合标准的AI技能。

官方文档: https://agentskills.io/specification

什么是Agent Skills？

Agent Skills是一种标准化的技能格式，允许AI助手：

  1. 发现技能 - 通过统一的元数据格式
  2. 激活技能 - 在需要时加载和执行特定技能
  3. 管理技能 - 组织、更新和验证技能

目录结构

一个标准的Agent Skill目录结构如下：

skill-name/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行代码
├── references/       # 可选：文档资料
├── assets/           # 可选：模板、资源
└── ...               # 任何其他文件或目录

SKILL.md格式

SKILL.md文件必须包含YAML frontmatter和Markdown内容。

Frontmatter字段

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

最小示例

---
name: skill-name
description: A description of what this skill does and when to use it.
---

完整示例

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

字段详解

name字段

  • 长度：1-64字符
  • 字符：仅限小写字母（a-z）、数字和连字符（-）
  • 不能以连字符开头或结尾
  • 不能包含连续连字符（--）
  • 必须与父目录名匹配

有效示例：

  • pdf-processing
  • data-analysis
  • code-review

无效示例：

  • PDF-Processing（大写不允许）
  • -pdf（不能以连字符开头）
  • pdf--processing（连续连字符不允许）

description字段

  • 长度：1-1024字符
  • 应描述技能功能和适用场景
  • 应包含帮助AI识别相关任务的关键词

好示例：

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.

compatibility字段

  • 可选，如果提供则长度1-500字符
  • 仅当技能有特定环境要求时才需要
  • 可指示目标产品、系统包、网络访问需求等

示例：

compatibility: Requires git, docker, jq, and access to the internet

可选目录

scripts/

包含可执行代码，脚本应该：

  • 自包含或明确记录依赖
  • 包含有用的错误信息
  • 优雅处理边界情况

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

references/

包含AI在需要时可以阅读的额外文档：

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

assets/

包含静态资源：

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

渐进式披露

技能应结构化以高效使用上下文：

  1. 元数据（约100个token）：name和description字段在启动时加载
  2. 指令（建议<5000个token）：技能激活时加载完整的SKILL.md内容
  3. 资源（按需）：仅在需要时加载文件

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

文件引用

在技能中引用其他文件时，使用相对于技能根目录的相对路径：

参见[参考指南](references/REFERENCE.md)了解详情。

运行提取脚本：
scripts/extract.py

保持文件引用从SKILL.md开始只有一级深度，避免深度嵌套的引用链。

验证

使用skills-ref参考库验证技能：

skills-ref validate ./my-skill

这会检查SKILL.md frontmatter是否有效并遵循所有命名约定。

最佳实践

1. 清晰的描述

确保描述既说明技能功能，又说明适用场景。

2. 适当的分类

使用有意义的关键词，帮助AI准确识别何时使用该技能。

3. 模块化设计

将复杂功能分解为多个小技能，而不是一个庞大的技能。

4. 完整文档

提供清晰的示例、边界情况处理和故障排除指南。

5. 保持更新

随着技能演进，及时更新文档和元数据。

实际应用

在OpenClaw中，Agent Skills用于：

  1. 扩展功能 - 添加新的能力到AI助手
  2. 标准化 - 确保技能的一致性和互操作性
  3. 发现 - 通过统一格式发现可用技能
  4. 管理 - 轻松安装、更新和删除技能

总结

Agent Skills规范为AI助手技能提供了一个标准化框架：

  1. 统一格式 - 通过SKILL.md定义技能
  2. 渐进式加载 - 优化上下文使用
  3. 模块化设计 - 支持技能组合和重用
  4. 验证机制 - 确保技能质量

掌握这个规范，你可以创建高质量、可互操作的AI技能，扩展AI助手的能力。

资源

本文基于Agent Skills官方规范文档编写，内容更新于2026年4月1日。

相关文章