企业官网建设流程全解析

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.md（YAML 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/*.md；
• SKILL.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-routing

validate: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 仓库中维护一个技能的标准流程如下：

新增技能：

1. 在 .agents/skills 下创建<skill-name>目录（小写字母、数字、连字符）；
2. 编写SKILL.md，frontmatter 仅含name（与目录同名）与description（≤1024 字符、含触发边界、含Use措辞），正文不超过 80 行；
3. 创建references/目录并放入至少一个.md细节文档；
4. 在SKILL.md正文中用references/xxx.md字样直接链接每个引用文件；
5. 在 ts/scripts/test-skill-routing.mjs 的probes数组中为它添加一个探针（代表性任务 + 4 个左右独特触发短语）；
6. 同步更新 validate-agent-skills.mjs 第 13-32 行的expectedSkills列表及 AGENTS.md 中的路由清单；
7. 运行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 Skills（name应与父目录一致、使用小写连字符标识符）三方的共同约定，并在此之上叠加了本仓库特有的约束：单一规范树 + 兼容符号链接、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