Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 48 lines 2.03 KB
Rendered Raw
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.