Composio 仓库 Agent Skills 维护指南SKILL.md 格式规范、兼容符号链接与双验证流水线【免费下载链接】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 开源仓库中本地 Agent Skills 技能树的维护规范涵盖.agents/skills规范目录结构、SKILL.md 的 YAML frontmatter 格式约束、第一层 references 引用约定以及validate:agent-skills与validate:skill-routing两套验证命令的底层实现与执行方式。读者将掌握如何在仓库中新增、修改、重组技能条目并理解触发描述description如何决定 Agent 的任务路由从而保证技能树可维护、可校验、可被 Agent 正确命中。一、技能树全景规范目录与兼容符号链接Composio 仓库将 Agent Skills 统一收纳在仓库根目录下的.agents/skills中这是全仓库唯一的规范技能树canonical tree。与很多仓库同时维护多份技能副本不同本仓库明确规定.agents/skills是权威来源.claude/skills是指向.agents/skills的兼容符号链接禁止维护并行的手工编辑副本。实测仓库符号链接状态确认了这一约定.claude/skills指向../.agents/skills而 AGENTS.md 第 13 行也明确写道 Treat.agents/skillsas the canonical local skill tree..claude/skillsis a compatibility symlink and must not be edited as a separate copy. 这样做的收益是不同 Agent 工具如 Claude、Codex、VS Code可以共享同一份技能定义避免多副本漂移导致的格式不一致与维护成本翻倍。当前技能树包含 18 个技能条目均以目录形式存在于 .agents/skills 下bug-fixing、cli-command、cli-e2e、cli-release、cross-sdk-parity、docs-decisions、eve、good-docs-audit、good-docs-writing、python-providers、python-release、python-sdk、python-testing、repo-guidance、skill-maintenance、typescript-providers、typescript-sdk、typescript-testing。每个技能目录必须且只需包含一份SKILL.mdYAML frontmatter 简短正文并在可选的references/目录中存放细节文档。二、SKILL.md 的结构与 frontmatter 硬性约束每个技能目录下都必须存在SKILL.md其首部是 YAML frontmatter仅允许两个键--- name: skill-name description: What the skill does and when to use it. ---以本仓库实际技能为例repo-guidance/SKILL.md 的 frontmatter 是--- name: repo-guidance description: Navigate the Composio SDK monorepo, branch and PR workflow, repo layout, generated-file boundaries, changesets, and shared maintenance rules. Use when work spans multiple packages, when deciding where code belongs, when preparing a PR, or when the user asks about repository conventions rather than a specific SDK implementation. ---而本文所讲解的技能维护入口 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. ---references/skill-format.md.agents/skills/skill-maintenance/references/skill-format.md为 frontmatter 制定了如下规则name必须与所在目录名完全一致name仅允许小写字母、数字和连字符description是 Agent 在加载正文之前看到的路由面routing surface必须写明触发边界trigger boundaries即什么情况下使用该技能保持SKILL.md简短详细的示例、命令配方与包特定说明应放入第一层references/*.mdSKILL.md中必须直接链接每个引用文件避免嵌套式的引用追引用除非仓库工具链明确需要 UI 元数据不要添加agents/openai.yaml。这些规则在验证脚本 validate-agent-skills.mjs 中均有对应实现构成了机器可执行的硬约束第 70-101 行解析 frontmatter仅允许description与name两个键多余键直接报错第 136-138 行name与目录名不一致即失败第 140-142 行name不匹配/^[a-z0-9-]$/即失败第 144-146 行description超过 1024 字符即失败第 148-150 行description中必须出现Use一词触发边界标记否则失败。三、references第一层引用约定references/是技能细节的存放处约定同样严格每个技能目录必须存在references/目录校验脚本第 157-161 行目录内必须包含至少一个.md文件第 163-169 行引用必须是第一层文件references/下不允许出现子目录且不允许非 Markdown 文件混入第 171-178 行SKILL.md正文必须显式包含对每个引用文件的链接标记格式为references/文件名第 180-185 行。以 skill-maintenance/SKILL.md 为例其正文只有三段但明确要求Readreferences/skill-format.mdbefore changing skill folders, validation, or compatibility mirrors.——这正是SKILL.md 保持简短、细节下沉到 references设计原则的直观体现。校验脚本会逐项检查SKILL.md内容是否包含references/skill-format.md字样确保引用链路真实可达不会出现引用了但找不到文件或有文件但没被链接的悬空状态。四、兼容符号链接的机器校验兼容层.claude/skills的正确性同样由校验脚本守护第 189-202 行脚本要求该路径必须存在且必须是符号链接其指向必须严格等于../.agents/skills。如果.claude/skills变成了普通目录、或者被指向了其他目标验证将直接失败。这也呼应了禁止手工维护第二份技能副本的约定——任何试图另起炉灶的做法都会被 CI 拦截。此外验证脚本还执行了更广的仓库级防护技能树分类门taxonomy gate第 13-32 行内置了 18 个期望技能名的字面列表与实际磁盘目录逐项比对增删技能必须同步维护该列表以及 AGENTS.md 中的路由清单必需引导文件检查第 34-44 行与第 204-208 行要求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等嵌套引导文件必须存在陈旧引用扫描第 254-295 行递归扫描仓库文本文件任何残留的docs/.claude、.claude/context、.claude/decisions、.claude/guides、.claude/rules、.Codex/rules、.cursor/rules、workspace/zen、CLI.md等陈旧路径都会报错——这是逐步把各类工具专属配置收敛为中性引导文件策略的落地命令名合法性校验第 299-421 行解析技能与引导文件中的命令行逐一核对pnpm run命令是否存在于根 package.json 脚本、bun run命令是否存在于 docs/package.json 脚本、make目标是否存在于 python/Makefile、nox -s会话是否存在于 python/noxfile.py杜绝文档中引用不存在的命令。五、双验证流水线格式校验与路由冒烟测试技能维护工作依赖两个 npm 脚本定义于根 package.json 第 56、58 行pnpm validate:agent-skills pnpm validate:skill-routingvalidate:agent-skills对应 ts/scripts/validate-agent-skills.mjs即前文所述的全量静态校验frontmatter 键与取值、name 与目录一致性、description 长度与Use触发词、SKILL.md 行数上限第 152-155 行要求不超过 80 行、references 目录形态、符号链接指向、分类门、必需引导文件、陈旧引用与命令名合法性。全部通过后输出Validated 18 canonical agent skills and guidance invariants.任一失败则以非零退出码结束并逐条打印错误。validate:skill-routing对应 ts/scripts/test-skill-routing.mjs是一个确定性的路由冒烟测试deterministic routing smoke test其设计意图在脚本头注释中讲得很清楚这不是 LLM 评测而是防止SKILL.md 的 description 编辑悄悄破坏任务路由的轻量回归护栏。工作原理如下内置 18 个探针probe每个探针包含一个代表性任务、期望命中的技能名以及一组该技能 description 中应包含的独特触发短语第 34-130 行对每个探针脚本将所有技能的 description 转为小写逐一统计触发短语作为子串的命中数并打分第 156-163 行断言期望技能是唯一的最高分获得者第 165-183 行若期望技能得分为 0说明 description 漂移、丢失了关键短语或存在并列/更高的其他技能说明出现了歧义重叠即失败并输出前四名得分详情覆盖度检查第 142-148 行每个技能必须至少有一个探针新增或重命名技能后如果忘记补充探针测试同样失败从而保证路由覆盖度始终跟随分类树。以skill-maintenance自身为例其探针是add or update an Agent Skill SKILL.md frontmatter and references期望短语包括SKILL.md frontmatter、compatibility symlinks、agent skills、skill taxonomy第 110-114 行与 skill-maintenance/SKILL.md 的 description 一一对应。这解释了为什么 description 的措辞必须精心设计它是 Agent 路由的唯一依据也是冒烟测试断言的唯一依据。六、标准维护工作流新增、修改与重组技能综合上述规范与源码约束在 Composio 仓库中维护一个技能的标准流程如下新增技能在 .agents/skills 下创建skill-name目录小写字母、数字、连字符编写SKILL.mdfrontmatter 仅含name与目录同名与description≤1024 字符、含触发边界、含Use措辞正文不超过 80 行创建references/目录并放入至少一个.md细节文档在SKILL.md正文中用references/xxx.md字样直接链接每个引用文件在 ts/scripts/test-skill-routing.mjs 的probes数组中为它添加一个探针代表性任务 4 个左右独特触发短语同步更新 validate-agent-skills.mjs 第 13-32 行的expectedSkills列表及 AGENTS.md 中的路由清单运行pnpm validate:agent-skills与pnpm validate:skill-routing全部通过后再提交。修改或重命名技能重命名需要同时处理目录名、frontmatter 的name、探针的expect字段与分类门列表仅改写description时必须重新审视探针短语是否仍然命中否则路由冒烟测试会以description drifted失败。删除技能同理需要同步移除探针与分类门条目确保两套验证始终通过。重组技能涉及移动 references 或拆分技能时注意 references 必须保持第一层文件形态SKILL.md中的链接标记必须与实际文件一一对应同时避免在仓库任何文本中引入docs/.claude等陈旧引用路径。七、设计思想小结从 references/skill-format.md 的Primary Sources Checked一节可以看到这套规范对齐了 OpenAI Codex技能为含SKILL.md、可选scripts/、references/、assets/、agents/的目录、Claude Agent Skills每个技能必须有带name与description的 frontmatter以及 VS Code Agent Skillsname应与父目录一致、使用小写连字符标识符三方的共同约定并在此之上叠加了本仓库特有的约束单一规范树 兼容符号链接、references 强制第一层、双验证流水线。其核心价值在于把技能树可维护性从口头约定升级为 CI 可执行的硬约束格式问题在提交前即被拦截路由回归由确定性冒烟测试守护分类变更必须同步三处磁盘目录、分类门、路由探针从而保证这 18 个技能无论被哪个 Agent 工具加载都能以一致、可预期的方式被正确路由与使用。【免费下载链接】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），仅供参考 Composio 仓库 Agent Skills 维护指南：SKILL.md 格式规范、兼容符号链接与双验证流水线
Composio 仓库 Agent Skills 维护指南SKILL.md 格式规范、兼容符号链接与双验证流水线【免费下载链接】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 开源仓库中本地 Agent Skills 技能树的维护规范涵盖.agents/skills规范目录结构、SKILL.md 的 YAML frontmatter 格式约束、第一层 references 引用约定以及validate:agent-skills与validate:skill-routing两套验证命令的底层实现与执行方式。读者将掌握如何在仓库中新增、修改、重组技能条目并理解触发描述description如何决定 Agent 的任务路由从而保证技能树可维护、可校验、可被 Agent 正确命中。一、技能树全景规范目录与兼容符号链接Composio 仓库将 Agent Skills 统一收纳在仓库根目录下的.agents/skills中这是全仓库唯一的规范技能树canonical tree。与很多仓库同时维护多份技能副本不同本仓库明确规定.agents/skills是权威来源.claude/skills是指向.agents/skills的兼容符号链接禁止维护并行的手工编辑副本。实测仓库符号链接状态确认了这一约定.claude/skills指向../.agents/skills而 AGENTS.md 第 13 行也明确写道 Treat.agents/skillsas the canonical local skill tree..claude/skillsis a compatibility symlink and must not be edited as a separate copy. 这样做的收益是不同 Agent 工具如 Claude、Codex、VS Code可以共享同一份技能定义避免多副本漂移导致的格式不一致与维护成本翻倍。当前技能树包含 18 个技能条目均以目录形式存在于 .agents/skills 下bug-fixing、cli-command、cli-e2e、cli-release、cross-sdk-parity、docs-decisions、eve、good-docs-audit、good-docs-writing、python-providers、python-release、python-sdk、python-testing、repo-guidance、skill-maintenance、typescript-providers、typescript-sdk、typescript-testing。每个技能目录必须且只需包含一份SKILL.mdYAML frontmatter 简短正文并在可选的references/目录中存放细节文档。二、SKILL.md 的结构与 frontmatter 硬性约束每个技能目录下都必须存在SKILL.md其首部是 YAML frontmatter仅允许两个键--- name: skill-name description: What the skill does and when to use it. ---以本仓库实际技能为例repo-guidance/SKILL.md 的 frontmatter 是--- name: repo-guidance description: Navigate the Composio SDK monorepo, branch and PR workflow, repo layout, generated-file boundaries, changesets, and shared maintenance rules. Use when work spans multiple packages, when deciding where code belongs, when preparing a PR, or when the user asks about repository conventions rather than a specific SDK implementation. ---而本文所讲解的技能维护入口 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. ---references/skill-format.md.agents/skills/skill-maintenance/references/skill-format.md为 frontmatter 制定了如下规则name必须与所在目录名完全一致name仅允许小写字母、数字和连字符description是 Agent 在加载正文之前看到的路由面routing surface必须写明触发边界trigger boundaries即什么情况下使用该技能保持SKILL.md简短详细的示例、命令配方与包特定说明应放入第一层references/*.mdSKILL.md中必须直接链接每个引用文件避免嵌套式的引用追引用除非仓库工具链明确需要 UI 元数据不要添加agents/openai.yaml。这些规则在验证脚本 validate-agent-skills.mjs 中均有对应实现构成了机器可执行的硬约束第 70-101 行解析 frontmatter仅允许description与name两个键多余键直接报错第 136-138 行name与目录名不一致即失败第 140-142 行name不匹配/^[a-z0-9-]$/即失败第 144-146 行description超过 1024 字符即失败第 148-150 行description中必须出现Use一词触发边界标记否则失败。三、references第一层引用约定references/是技能细节的存放处约定同样严格每个技能目录必须存在references/目录校验脚本第 157-161 行目录内必须包含至少一个.md文件第 163-169 行引用必须是第一层文件references/下不允许出现子目录且不允许非 Markdown 文件混入第 171-178 行SKILL.md正文必须显式包含对每个引用文件的链接标记格式为references/文件名第 180-185 行。以 skill-maintenance/SKILL.md 为例其正文只有三段但明确要求Readreferences/skill-format.mdbefore changing skill folders, validation, or compatibility mirrors.——这正是SKILL.md 保持简短、细节下沉到 references设计原则的直观体现。校验脚本会逐项检查SKILL.md内容是否包含references/skill-format.md字样确保引用链路真实可达不会出现引用了但找不到文件或有文件但没被链接的悬空状态。四、兼容符号链接的机器校验兼容层.claude/skills的正确性同样由校验脚本守护第 189-202 行脚本要求该路径必须存在且必须是符号链接其指向必须严格等于../.agents/skills。如果.claude/skills变成了普通目录、或者被指向了其他目标验证将直接失败。这也呼应了禁止手工维护第二份技能副本的约定——任何试图另起炉灶的做法都会被 CI 拦截。此外验证脚本还执行了更广的仓库级防护技能树分类门taxonomy gate第 13-32 行内置了 18 个期望技能名的字面列表与实际磁盘目录逐项比对增删技能必须同步维护该列表以及 AGENTS.md 中的路由清单必需引导文件检查第 34-44 行与第 204-208 行要求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等嵌套引导文件必须存在陈旧引用扫描第 254-295 行递归扫描仓库文本文件任何残留的docs/.claude、.claude/context、.claude/decisions、.claude/guides、.claude/rules、.Codex/rules、.cursor/rules、workspace/zen、CLI.md等陈旧路径都会报错——这是逐步把各类工具专属配置收敛为中性引导文件策略的落地命令名合法性校验第 299-421 行解析技能与引导文件中的命令行逐一核对pnpm run命令是否存在于根 package.json 脚本、bun run命令是否存在于 docs/package.json 脚本、make目标是否存在于 python/Makefile、nox -s会话是否存在于 python/noxfile.py杜绝文档中引用不存在的命令。五、双验证流水线格式校验与路由冒烟测试技能维护工作依赖两个 npm 脚本定义于根 package.json 第 56、58 行pnpm validate:agent-skills pnpm validate:skill-routingvalidate:agent-skills对应 ts/scripts/validate-agent-skills.mjs即前文所述的全量静态校验frontmatter 键与取值、name 与目录一致性、description 长度与Use触发词、SKILL.md 行数上限第 152-155 行要求不超过 80 行、references 目录形态、符号链接指向、分类门、必需引导文件、陈旧引用与命令名合法性。全部通过后输出Validated 18 canonical agent skills and guidance invariants.任一失败则以非零退出码结束并逐条打印错误。validate:skill-routing对应 ts/scripts/test-skill-routing.mjs是一个确定性的路由冒烟测试deterministic routing smoke test其设计意图在脚本头注释中讲得很清楚这不是 LLM 评测而是防止SKILL.md 的 description 编辑悄悄破坏任务路由的轻量回归护栏。工作原理如下内置 18 个探针probe每个探针包含一个代表性任务、期望命中的技能名以及一组该技能 description 中应包含的独特触发短语第 34-130 行对每个探针脚本将所有技能的 description 转为小写逐一统计触发短语作为子串的命中数并打分第 156-163 行断言期望技能是唯一的最高分获得者第 165-183 行若期望技能得分为 0说明 description 漂移、丢失了关键短语或存在并列/更高的其他技能说明出现了歧义重叠即失败并输出前四名得分详情覆盖度检查第 142-148 行每个技能必须至少有一个探针新增或重命名技能后如果忘记补充探针测试同样失败从而保证路由覆盖度始终跟随分类树。以skill-maintenance自身为例其探针是add or update an Agent Skill SKILL.md frontmatter and references期望短语包括SKILL.md frontmatter、compatibility symlinks、agent skills、skill taxonomy第 110-114 行与 skill-maintenance/SKILL.md 的 description 一一对应。这解释了为什么 description 的措辞必须精心设计它是 Agent 路由的唯一依据也是冒烟测试断言的唯一依据。六、标准维护工作流新增、修改与重组技能综合上述规范与源码约束在 Composio 仓库中维护一个技能的标准流程如下新增技能在 .agents/skills 下创建skill-name目录小写字母、数字、连字符编写SKILL.mdfrontmatter 仅含name与目录同名与description≤1024 字符、含触发边界、含Use措辞正文不超过 80 行创建references/目录并放入至少一个.md细节文档在SKILL.md正文中用references/xxx.md字样直接链接每个引用文件在 ts/scripts/test-skill-routing.mjs 的probes数组中为它添加一个探针代表性任务 4 个左右独特触发短语同步更新 validate-agent-skills.mjs 第 13-32 行的expectedSkills列表及 AGENTS.md 中的路由清单运行pnpm validate:agent-skills与pnpm validate:skill-routing全部通过后再提交。修改或重命名技能重命名需要同时处理目录名、frontmatter 的name、探针的expect字段与分类门列表仅改写description时必须重新审视探针短语是否仍然命中否则路由冒烟测试会以description drifted失败。删除技能同理需要同步移除探针与分类门条目确保两套验证始终通过。重组技能涉及移动 references 或拆分技能时注意 references 必须保持第一层文件形态SKILL.md中的链接标记必须与实际文件一一对应同时避免在仓库任何文本中引入docs/.claude等陈旧引用路径。七、设计思想小结从 references/skill-format.md 的Primary Sources Checked一节可以看到这套规范对齐了 OpenAI Codex技能为含SKILL.md、可选scripts/、references/、assets/、agents/的目录、Claude Agent Skills每个技能必须有带name与description的 frontmatter以及 VS Code Agent Skillsname应与父目录一致、使用小写连字符标识符三方的共同约定并在此之上叠加了本仓库特有的约束单一规范树 兼容符号链接、references 强制第一层、双验证流水线。其核心价值在于把技能树可维护性从口头约定升级为 CI 可执行的硬约束格式问题在提交前即被拦截路由回归由确定性冒烟测试守护分类变更必须同步三处磁盘目录、分类门、路由探针从而保证这 18 个技能无论被哪个 Agent 工具加载都能以一致、可预期的方式被正确路由与使用。【免费下载链接】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），仅供参考