Agent Skills 开放规范

Overview

Agent Skills 开放规范（agentskills.io）定义了 Skill 的标准格式。本文梳理其核心规范要点，并与 Anthropic 官方 Skills 仓库的实践对照。

为什么重要

agentskills.io 与 Anthropic 官方仓库都在塑造 Skill 标准格式，但两者口径有微妙差异：metadata 字段、文件结构、gating 机制各有侧重。如果只读单一来源容易踩坑——比如 description 写法、可选字段优先级、平台兼容性。本文是两者的对照清单，让你写的 Skill 既符合开放规范也能在 Claude / OpenClaw 等多个 runtime 跑得通。

目录结构

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

SKILL.md 格式

Frontmatter 字段

字段	必需	约束
name	✅	≤64 字符，小写+数字+连字符，必须与父目录名一致
description	✅	≤1024 字符，描述做什么和何时使用
license	❌	许可证名称
compatibility	❌	≤500 字符，环境要求
metadata	❌	任意键值映射
allowed-tools	❌	空格分隔的预批准工具（实验性）

name 规则

• 1-64 字符，仅 a-z、0-9、连字符
• 不能以连字符开头/结尾，不能含连续连字符
• 必须匹配父目录名

有效：pdf-processing、data-analysis 无效：PDF-Processing（大写）、-pdf（开头连字符）、pdf--processing（连续连字符）

description 规则

• 1-1024 字符
• 描述做什么和何时使用
• 包含帮助 Agent 识别相关任务的关键词

渐进式披露

1. Metadata（~100 tokens）：启动时加载所有 Skill 的 name + description
2. Instructions（建议 < 5000 tokens）：激活时加载完整 body
3. Resources（按需）：scripts/references/assets 仅在需要时加载

主 SKILL.md 保持在 500 行以下。

文件引用

• 从 Skill 根目录的相对路径
• 保持一层深度，避免深层嵌套

Anthropic 官方 Skills 仓库

仓库结构：./skills（技能示例）、./spec（规范）、./template（模板）

四类技能：创意与设计、开发与技术、企业与沟通、文档技能（DOCX/PDF/PPTX/XLSX）。

文档技能为”actively used in a production AI application”的参考实现。

验证工具

skills-ref validate ./my-skill

可选字段详解

license

简短指定许可证。建议保持一行：

license: Proprietary. LICENSE.txt has complete terms

compatibility

仅在有特定环境需求时包含（≤500 字符）：

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

大多数 Skill 不需要此字段。

metadata

字符串键值映射，用于存储规范未定义的附加属性：

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

建议键名保持合理唯一以避免冲突。

allowed-tools

以空格分隔的预批准工具列表（实验性）：

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

不同 Agent 实现对此字段的支持可能不同。

Body 内容规范

Frontmatter 后的 Markdown body 无格式限制，但建议包含：

• 分步指令
• 输入输出示例
• 常见边界情况

一旦 Agent 决定激活 Skill，完整 body 加载进上下文。考虑将长内容拆分到引用文件。

可选目录说明

• scripts/：自包含、明确依赖文档、有帮助的错误消息、优雅处理边界情况的可执行代码。支持 Python/Bash/JavaScript。
• references/：Agent 按需加载的文档。保持单个文件聚焦——较小文件 = 更少上下文占用。
• assets/：模板、图片、数据文件（查找表、schema）等静态资源。

验证工具

skills-ref validate ./my-skill

See Also

• Skill 开发综合指南 — Skill 开发完整框架与最佳实践
• Skill 评估与迭代 — Eval 驱动的品质改进
• 优化 Skill Description — 提升 Skill 触发准确率
• 高质量 Skill 方法论 — 5 步写出专家品质 Skill
• Agent 开发综合指南 — Agent 开发完整框架