跳到主要内容

Agent Skills 规范对照与宿主接入

目录​

本文解决什么问题​

agentskills.io 用一套开放、可移植的约定描述「Skill 文件夹里放什么、元数据怎么写、宿主怎么加载」。本站在 Skill 编写规范 与 治理与测试 里讲的是通用工程实践；本文把官方站点的章节结构与实现者视角的接入要点集中成一页，便于你对照原文迭代，而不必在浏览器里逐个点左侧导航。

下列链接均为官网页面（与 llms.txt 索引 一致）。

agentskills.io 文档地图​

主题说明原文
总览站点首页与叙事入口Home
Skill 是什么文件夹结构、SKILL.md、发现→激活→执行What are skills?
规范name/description 等字段约束、目录、references/ 与 assets/Specification
快速上手最小示例（如掷骰子）、VS Code 下 .agents/skills/Quickstart
最佳实践从真实任务提炼、控制篇幅、预设默认值、GotchasBest practices
优化描述description 如何写得易触发、评测集与防过拟合Optimizing descriptions
评测输出evals/evals.json、断言、与无 Skill 基线对比Evaluating skills
使用脚本uvx/npx 等一次性命令、自包含脚本、代理友好接口Using scripts
宿主接入发现路径、目录解析、披露目录、激活、上下文管理Adding skills support
客户端展示各产品/工具的支持情况Client showcase

规范全文还提到用 skills-ref 做校验（skills-ref validate ./my-skill），以及示例仓库 anthropics/skills。

核心机制：渐进披露​

官方用渐进披露控制上下文：启动时只加载每个 Skill 的元数据（主要是 name + description），任务匹配后再加载完整 SKILL.md，需要时再读 scripts/、references/、assets/。规范里建议把主 SKILL.md 控制在约 500 行、正文约 5000 token 以内，细节拆到引用文件，避免一次塞满上下文。详见 Specification / Progressive disclosure 与 What are skills? / How skills work。

写作侧：与规范要点对齐​

更细的 YAML 字段表、好/坏 description 示例、目录约定已写入本站 Skill 编写规范与 SKILL.md 模板。此处只强调与官网一致的决策点：

  • description 既要写「做什么」，也要写「何时用」，并包含能帮助匹配的用户说法或场景词；过短或过泛都会让发现阶段失效（见 Optimizing descriptions）。
  • 补全代理不知道的信息：项目约定、易错点、固定命令序列；避免复述模型已具备的常识（见 Best practices / Spending context wisely）。
  • 引用文件保持一层相对路径、按需加载：在正文里写清「何种情况下打开哪份 reference」，而不是把全书塞进 SKILL.md（见 Specification / File references）。

评测与迭代方法（断言、基线对比、描述触发集）见本站 Skill 治理、测试与版本发布，并与官网 Evaluating skills 对照使用。

实现侧：宿主如何接入​

Adding skills support 面向「自研 Agent / IDE 插件」的实现者，主线可概括为五步（与上文渐进披露对应）：

  1. 发现：在会话开始时扫描 Skill 目录，找到含 SKILL.md 的子目录；常见范围包括项目内与用户级，并广泛采用 .agents/skills/ 约定以便跨客户端互操作（规范不强制磁盘路径，但文档推荐扫描该目录及宿主自有路径）。云端/沙箱环境需用注册表、上传或内置资源代替本机扫描。
  2. 解析：分离 YAML frontmatter 与正文；对「不合法但常见」的 YAML 可做容错；无 description 的 Skill 不宜进入目录。
  3. 披露：只把 name、description（及必要时 location）提供给模型，占用约每 Skill 数十到百级 token；无 Skill 时不要塞空块误导模型。
  4. 激活：由模型根据任务匹配后读取完整说明，或通过专用工具注入；需约定工作目录为 Skill 根目录，以便解析 scripts/... 相对路径。
  5. 会话内管理：若实现上下文压缩，应避免把已加载的 Skill 说明误删；可去重重复激活。

此外：同名 Skill 的优先级（通常项目级覆盖用户级）、不可信仓库中的项目级 Skill（需信任门槛）、权限白名单（避免每读一个 bundle 内文件就弹一次授权）在原文中都有专门小节，实现宿主时建议通读一遍。

脚本与一次性命令​

Using scripts 建议：能用现成 CLI 时可用 uvx、pipx、npx、bunx 等带版本号的一次性调用；复杂逻辑则放入 scripts/ 并保证非交互、--help 自说明、错误信息可行动、结构化输出（stdout 给数据、stderr 给日志），便于代理解析与重试。Python 可结合 PEP 723 内联依赖与 uv run 等模式减少环境摩擦。

延伸阅读​