Agent Skills 开放标准及其最佳实践
Agent Skills 是由 agentskills.io 推出的轻量级、通用、模型无关的 AI agent(智能体)技能开放标准,核心设计理念是渐进式披露和上下文高效利用,旨在解决 AI agent技能的可复用性、可分享性和执行可靠性问题。以下是对其规范、最佳实践和描述优化的系统总结,并对比当前行业其他相关标准。
一、Agent Skills 核心规范(Specification)
1. 目录结构
一个技能是一个独立目录,必须包含 SKILL.md 核心文件,可搭配三个可选目录:
2. SKILL.md 核心格式
文件由YAML 前置元数据和Markdown 指令主体两部分组成。
(1)YAML 前置元数据字段
字段 | 必填 | 约束与说明 |
name | 是 | 1-64 字符,仅允许小写字母、数字和连字符;不能首尾或连续使用连字符;必须与父目录名完全一致 |
description | 是 | 1-1024 字符,必须同时说明技能做什么和什么时候使用,包含代理可识别的关键词 |
license | 否 | 许可证名称或指向许可证文件的引用 |
compatibility | 否 | 1-500 字符,说明环境要求(如 Python 版本、系统依赖、网络权限),大多数技能不需要 |
metadata | 否 | 任意键值对,用于存储自定义属性(如作者、版本) |
allowed-tools | 否 | 实验性字段,空格分隔的预批准工具列表 |
示例:
(2)Markdown 指令主体
无强制格式限制,推荐包含:
分步操作指南
输入输出示例
常见边缘情况处理
错误处理建议
核心约束:主体内容建议控制在500行/5000tokens以内,详细内容移至references/目录按需加载。
3. 渐进式披露原则
标准最核心的设计,通过分层加载最大化上下文效率:
元数据层(~100token):启动时加载所有技能的name和description,用于判断是否触发
指令层(<5000token):技能被激活时加载完整SKILL.md主体
资源层(按需加载):仅在需要时加载scripts/、references/、assets/中的文件
4. 验证方法
使用官方提供的skills-ref工具验证技能合规性:
运行:skills-ref validate ./my-skill
该工具会检查SKILL.md元数据格式、命名规范和目录结构。
二、最佳实践分类整理
1. 技能来源:基于真实专业知识
避免让 LLM 凭空生成技能,所有有效技能都应扎根于实际经验:
从实际任务中提取:与代理协作完成真实任务,记录成功步骤、纠正点、输入输出格式和项目特定约束
从现有项目工件中合成:使用内部文档、运行手册、API 规范、代码评审意见、故障报告和版本控制历史作为素材
通过实际执行迭代优化:运行技能处理真实任务,分析执行轨迹(而非仅最终输出),识别误触发、遗漏步骤和冗余内容
2. 上下文管理:明智使用有限 toke…