Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 07:15 UTC
| 1 | # Skill Format |
| 2 | |
| 3 | ## Canonical Tree |
| 4 | |
| 5 | - `.agents/skills` is canonical. |
| 6 | - `.claude/skills` is a compatibility symlink to `.agents/skills`. |
| 7 | - Do not maintain parallel hand-edited skill copies. |
| 8 | |
| 9 | ## Required Structure |
| 10 | |
| 11 | Each skill directory must contain `SKILL.md` with YAML frontmatter: |
| 12 | |
| 13 | ```yaml |
| 14 | --- |
| 15 | name: skill-name |
| 16 | description: What the skill does and when to use it. |
| 17 | --- |
| 18 | ``` |
| 19 | |
| 20 | Rules: |
| 21 | |
| 22 | - `name` must match the directory name. |
| 23 | - Use lowercase letters, digits, and hyphens only. |
| 24 | - Include trigger boundaries in `description`; it is the routing surface agents see before loading the body. |
| 25 | - Keep `SKILL.md` short. Put detailed examples, command recipes, and package-specific notes in first-level `references/*.md`. |
| 26 | - Link every reference directly from `SKILL.md`; avoid nested reference-chasing. |
| 27 | - Do not add `agents/openai.yaml` unless repo tooling explicitly needs UI metadata. |
| 28 | |
| 29 | ## Primary Sources Checked |
| 30 | |
| 31 | - OpenAI Codex Agent Skills docs: skills are directories with `SKILL.md`, optional `scripts/`, `references/`, `assets/`, and optional `agents/`. |
| 32 | - Claude Agent Skills docs: every skill requires `SKILL.md` frontmatter with `name` and `description`. |
| 33 | - VS Code Agent Skills docs: `name` should match the parent directory and use lowercase hyphenated identifiers. |
| 34 | |
| 35 | ## Validation |
| 36 | |
| 37 | Run: |
| 38 | |
| 39 | ```bash |
| 40 | bun run validate:agent-skills |
| 41 | bun run validate:skill-routing |
| 42 | ``` |
| 43 | |
| 44 | Both validators are deterministic, and `.github/workflows/agent-substrate.yml` runs them in CI on every push and pull request — the stale-guidance scan covers the whole repo, so any change can affect the result. |
| 45 | |
| 46 | `validate:agent-skills` checks frontmatter, names, reference links, compatibility symlink state, stale guidance references, and known command names. |
| 47 | |
| 48 | `validate:skill-routing` is a deterministic routing smoke test (`ts/scripts/test-skill-routing.ts`): for representative tasks it asserts the expected skill is the unique top match by distinctive trigger phrases, and fails if any skill has no probe. When you add or rename a skill, or rewrite a `description`, add or update its probe so routing stays covered. |