Composio 仓库 Agent Skills 格式规范SKILL.md 目录结构、frontmatter 规则与自动化校验指南【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本指南以 Composio 仓库 skill-format.md 为骨架系统讲解仓库内 Agent Skills 的标准目录结构、SKILL.md的 YAML frontmatter 书写规范、references/引用组织方式以及配套的两条校验命令pnpm validate:agent-skills与pnpm validate:skill-routing的底层实现原理。读完本文你将掌握在.agents/skills下新增、重命名、改写一个 Skill 时必须遵守的格式约定并能用源码级的校验逻辑验证自己的改动是否合规。规范树Canonical Tree单一事实来源与兼容符号链接仓库对 Skill 的存放位置有明确约定任何 Skill 维护工作都必须先理解这三条原则.agents/skills是唯一规范canonical的技能树根目录所有 Skill 定义都以它为准.claude/skills是.agents/skills的兼容符号链接compatibility symlink供 Claude Code 生态读取禁止维护并行的手工编辑副本Do not maintain parallel hand-edited skill copies避免两份副本漂移导致行为不一致。在仓库中执行ls -la .claude/可以看到该链接的实际状态.claude/skills - ../.agents/skills也就是说.claude/skills并非真实目录而是指向.agents/skills的软链接。这一点在根目录 AGENTS.md 中同样被强调.claude/skills是兼容符号链接不得作为独立副本编辑。校验脚本 validate-agent-skills.mjs 会强制检查这一点如果.claude/skills不是符号链接或链接目标不是../.agents/skills校验会直接失败。当前仓库的规范技能树包含 18 个 Skill.agents/skills/下的每个目录即一个 Skill例如bug-fixing、python-sdk、typescript-testing、skill-maintenance等覆盖代码修复、CLI 开发、SDK 实现、文档写作与校验等各类开发任务。必需目录结构每个 Skill 目录都必须有 SKILL.md每个 Skill 目录内必须包含一个SKILL.md文件且该文件必须以 YAML frontmatter 开头--- name: skill-name description: What the skill does and when to use it. ---以仓库中真实存在的 skill-maintenance/SKILL.md 为例--- name: skill-maintenance description: Create, update, validate, or reorganize repo-local Agent Skills under .agents/skills, including SKILL.md frontmatter, first-level references, compatibility symlinks, and validation scripts. Use only for skill-tree maintenance, skill taxonomy changes, or agent-guidance validation work. ---再如 python-sdk/SKILL.md--- name: python-sdk description: Implement or modify Python SDK behavior under python/composio, including tools, toolkits, sessions, auth configs, connected accounts, client integration, and shared Python models. Use for Python core runtime/API work; pair with python-testing and cross-sdk-parity when TypeScript must match. ---frontmatter 字段规则字段规则校验实现依据name必须与所在目录名完全一致validate-agent-skills.mjs 比对name与目录名不一致即报错name字符集仅允许小写字母、数字与连字符^[a-z0-9-]$validate-agent-skills.mjs 正则校验description说明该 Skill 做什么以及何时使用是 Agent 在加载正文之前看到的路由表面routing surface因此必须包含触发边界validate-agent-skills.mjs 要求 description 必须包含 Use 字样以声明触发边界description长度建议精炼硬性上限 1024 字符validate-agent-skills.mjs 超长即报错其他键只允许name与description两个键出现其他键如多余的version会被拒绝validate-agent-skills.mjs 检查allowed [description, name]为什么description如此重要因为 Skill 的路由机制在加载正文之前只会看到 frontmatter 中的description与name。Agent 依据这些短文本判断当前任务该用哪个 Skill。因此description中应写明触发边界trigger boundaries——即在什么场景下使用、用于何种类型的工作让路由足够有区分度避免多个 Skill 的描述产生歧义重叠。SKILL.md 正文保持精简详细内容放入 referencesSKILL.md的正文部分应保持简短该校验脚本将 80 行作为软上限见 validate-agent-skills.mjs其职责是路由与入口。详细的示例、命令配方command recipes、针对具体包/语言的注意事项应放入一级references/*.md文件中。以skill-maintenance为例其SKILL.md正文仅寥寥数行指向格式规范Use this skill when editing the repo-local skill tree. Read references/skill-format.md before changing skill folders, validation, or compatibility mirrors.而 references/skill-format.md 才是承载完整格式规范与校验命令的地方——也就是本文所依据的文档。references/ 的组织约束references/目录必须存在且必须包含至少一个 Markdown 文件references/下只允许一级文件不允许再嵌套子目录避免引用套引用的链条式追查每个references/*.md文件必须被SKILL.md直接链接——SKILL.md正文中必须包含references/文件名.md这样的标记否则校验失败目录内不允许出现非.md文件。以上约束均由 validate-agent-skills.mjs 逐条强制缺失references目录、目录内无 md 文件、出现子目录、出现非 md 文件、SKILL.md 未链接某个 reference都会产生错误。agents/ 目录的补充说明除非仓库工具链确实需要 UI 元数据否则不要在 Skill 目录中添加agents/openai.yaml。格式规范引用了 OpenAI Codex、Claude、VS Code 三方的 Agent Skills 文档作为依据Skill 本质是含SKILL.md的目录可选scripts/、references/、assets/以及可选的agents/Claude 要求每个 Skill 的 frontmatter 必须有name与descriptionVS Code 要求name与父目录一致并使用小写连字符标识符——这三条外部约束与仓库内部约定完全一致。自动化校验两条命令守住格式红线仓库在根目录 package.json 注册了两条校验脚本pnpm validate:agent-skills pnpm validate:skill-routing1. validate:agent-skills结构完整性与全局一致性该命令实际执行node ts/scripts/validate-agent-skills.mjs其检查面包括frontmatter 解析每个SKILL.md必须有标准---包裹的 YAML 头逐行解析键值对拒绝不支持的键、缺失的name/description名称一致性name必须与目录名完全一致且只能由小写字母、数字、连字符组成description 约束长度不得超过 1024 字符且必须包含 Use 以声明触发边界SKILL.md 长度正文不得超过 80 行references 完整性目录必须存在、必须含 md 文件、只允许一级文件、每个 reference 必须被 SKILL.md 链接兼容符号链接状态.claude/skills必须是符号链接且指向../.agents/skills技能树分类学门禁taxonomy gate脚本内置expectedSkills列表18 个 Skill 名与磁盘上.agents/skills的实际目录逐一对齐增删 Skill 而不更新此列表会导致校验失败过期指南引用扫描全仓库遍历文本文件扫描docs/.claude、.claude/context、.claude/decisions、.cursor/rules等废弃路径模式防止残留旧版工具链的指引文件已知命令名检查解析技能树内所有 md 文件与各层级AGENTS.md中的pnpm run ...、bun run ...、make ...、nox -s ...命令与根目录 package.json、docs/package.json、python/Makefile、python/noxfile.py 中真实存在的脚本/目标/会话做比对杜绝文档中出现不存在的命令必需指引文件检查要求AGENTS.md、docs/AGENTS.md、ts/AGENTS.md、ts/packages/core/AGENTS.md、ts/packages/providers/AGENTS.md、ts/packages/cli/AGENTS.md、ts/e2e-tests/AGENTS.md、python/AGENTS.md、python/providers/AGENTS.md等分层指引文件必须存在。可以看出validate:agent-skills不只是格式检查它把技能树分类学、兼容链接、过期路径清理、命令真实性绑定在一起作为仓库 Agent 引导体系的全局不变量门禁。2. validate:skill-routing确定性的路由冒烟测试该命令执行node ts/scripts/test-skill-routing.mjs这是一个轻量、确定性的路由评测non-LLM eval专门防止改了一行 description 就悄悄破坏任务路由这类回归。其工作原理为每个 Skill 定义一个probe探针一条代表性任务 一组区分性触发短语distinctive trigger phrases对每个 probe遍历全部 Skill 的description统计触发短语命中的次数大小写不敏感的子串匹配作为得分断言期望的 Skill 是唯一的最高分unique top scorer覆盖检查每个 Skill 必须至少有一个 probe否则校验失败从而保证路由测试覆盖度与技能树分类学同步增长。以skill-maintenance的 probe 为例test-skill-routing.mjs{ task: add or update an Agent Skill SKILL.md frontmatter and references, expect: skill-maintenance, terms: [SKILL.md frontmatter, compatibility symlinks, agent skills, skill taxonomy], },该 probe 对应的任务添加或更新 Agent Skill 的 SKILL.md frontmatter 与 references预期唯一命中skill-maintenance触发短语取自其description中的关键区分词。这种设计能捕获两类常见回归期望技能描述漂移若某次改写删掉了让它成为明显匹配的关键词如去掉了 compatibility symlinksprobe 得分降为 0测试失败歧义重叠增长若另一个 Skill 的描述中加入了大量与本 Skill 重叠的词语导致最高分不再唯一测试同样失败并输出得分排行供排查。此外由于该脚本要求每个 Skill 都必须有 probe当你新增或重命名一个 Skill或重写某个description时必须同步在 test-skill-routing.mjs 中添加或更新对应 probe路由覆盖才能跟得上技能树的变化。实操指南如何安全地新增或修改一个 Skill结合以上格式规范与校验逻辑在 Composio 仓库中维护 Skill 的标准流程如下确认适用场景涉及技能树维护、Skill 分类学变更或 Agent 引导校验工作时先阅读 skill-format.md即本文依据并参考 skill-maintenance/SKILL.md 的指引创建目录与 frontmatter在.agents/skills/下新建目录目录名使用小写字母、数字、连字符SKILL.md顶部写入含name与目录名一致与description含 Use 触发边界、不超过 1024 字符的 YAML frontmatter拆分正文与 referencesSKILL.md正文保持 80 行以内的精简入口在正文中直接链接每个references/*.md文件如Read \references/skill-format.md before ...详细示例与命令配方放入一级 references 文件同步分类学列表若新增/重命名 Skill同步更新 validate-agent-skills.mjs 中的expectedSkills列表与 AGENTS.md 中的技能树说明使三处保持一致添加路由探针在 test-skill-routing.mjs 中为 Skill 添加 probe任务描述 区分性触发短语确保它是该任务的唯一最高分运行校验pnpm validate:agent-skills pnpm validate:skill-routing两条命令全部通过后才算完成一次合规的 Skill 维护。小结Composio 仓库的 Agent Skills 体系以.agents/skills为唯一规范树、.claude/skills为兼容符号链接通过精简短小的SKILL.md 一级references/*.md的目录结构实现路由与详情的分离。frontmatter 的name必须匹配目录名且只含小写字母/数字/连字符description是 Agent 路由所依赖的触发面。而 validate-agent-skills.mjs 与 test-skill-routing.mjs 两条校验脚本分别从结构完整性、分类学一致性、过期引用清理、命令真实性以及确定性路由覆盖五个维度守住格式红线——任何新增、重命名或改写 description 的操作都应以这两条命令的通过作为完成标准。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考