Skill Format
Canonical Tree
.agents/skillsis canonical..claude/skillsis a compatibility symlink to.agents/skills.- Do not maintain parallel hand-edited skill copies.
Required Structure
Each skill directory must contain SKILL.md with YAML frontmatter:
---
name: skill-name
description: What the skill does and when to use it.
---Rules:
namemust match the directory name.- Use lowercase letters, digits, and hyphens only.
- Include trigger boundaries in
description; it is the routing surface agents see before loading the body. - Keep
SKILL.mdshort. Put detailed examples, command recipes, and package-specific notes in first-levelreferences/*.md. - Link every reference directly from
SKILL.md; avoid nested reference-chasing. - Do not add
agents/openai.yamlunless repo tooling explicitly needs UI metadata.
Primary Sources Checked
- OpenAI Codex Agent Skills docs: skills are directories with
SKILL.md, optionalscripts/,references/,assets/, and optionalagents/. - Claude Agent Skills docs: every skill requires
SKILL.mdfrontmatter withnameanddescription. - VS Code Agent Skills docs:
nameshould match the parent directory and use lowercase hyphenated identifiers.
Validation
Run:
bun run validate:agent-skills
bun run validate:skill-routingBoth 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.
validate:agent-skills checks frontmatter, names, reference links, compatibility symlink state, stale guidance references, and known command names.
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.