| name | skill-add |
| description | Add a new agent skill end-to-end — invoke when creating a new file under `.agents/skills/`. Runs the composition gate, chooses the name and `ref-` prefix, drafts a triggering description and a body that satisfies the effectiveness and structural standards, cross-links parents, registers the catalog README row, and runs `skill-review` |
Add an Agent Skill
End-to-end workflow for creating a new skill at .agents/skills/<name>/SKILL.md. Wraps ref-skill-authoring-standards (structure) + ref-skill-effectiveness (content) + ref-agents-md-curation (decide whether the content belongs in AGENTS.md instead).
A new skill that no parent invokes is invisible. The Composition gate at step 2 is the most important step — run it before drafting anything.
Steps
-
Decide reference vs workflow. Apply ref-skill-authoring-standards Naming and the prefix rule. A workflow is a verb-noun action a human invokes directly. A reference is a noun-phrase standards document loaded by other skills.
-
Composition gate. Required first design step.
- Search the catalog
.agents/skills/README.md for an existing skill that already covers this concern. If found, edit that skill instead. Stop here.
- Identify which existing skills the new skill will invoke (its children).
- Identify which existing skills will invoke the new skill (its parents).
- If the new skill would have exactly one parent and no independent trigger, it is a section of that parent. Inline it; do not create a new file.
- Apply
ref-skill-authoring-standards Composition is the architecture extraction and merge triggers.
-
Decide skill vs AGENTS.md vs both. Apply ref-agents-md-curation What belongs in AGENTS.md and What does NOT belong in AGENTS.md. If the content fits both, pick the single source of truth and decide which file points to which.
-
Pick the name and prefix. Apply ref-skill-authoring-standards Naming and the prefix rule. The prefix rule answers one question: will any human ever invoke this skill directly? If yes (even occasionally), no prefix — even if other skills also reference it. If no, prefix with ref-.
- The
name must be lowercase letters, numbers, and hyphens only, at most 64 characters, and identical to the directory name. The spec rejects anything else.
- A
ref--prefixed skill also carries user-invocable: false (ref-skill-authoring-standards Frontmatter contract). Unprefixed workflows omit the key.
-
Draft the description. Apply ref-skill-effectiveness Triggerability. Third person; state what the skill does and when to use it; front-load the trigger so truncation cannot eat it; add the "not for X" clause when a sibling is ambiguous.
- Run the triggerability test: read your draft alongside the ten nearest sibling descriptions in the catalog. Given a representative task, would a reader pick your skill from descriptions alone? If no, rewrite.
-
Draft the body. Apply ref-skill-authoring-standards Structure of the SKILL.md body for form, and ref-skill-effectiveness (Actionability, Outcome orientation, Examples, Clarity and writing standards) for content.
- Workflow: imperative numbered steps; one action and one verifiable outcome per step.
- Reference: lead sentence + named-bold sub-bullets; fenced code blocks for canonical forms; canonical-implementation pointers wherever a real exemplar exists.
- Match specificity to fragility (
ref-skill-authoring-standards Degrees of freedom): exact commands where the operation is fragile, objective-and-constraints where several approaches are valid. Assume the agent is competent — a rule earns its tokens by carrying a project-specific opinion or a non-obvious constraint, not general good practice.
- Cross-reference children with
Apply <skill> — never paraphrase. Cite another skill's section by name, never by number.
- Reference files and skills per
ref-skill-authoring-standards Referencing files and skills: own bundled files as markdown links, other skills by name, source/test code as backtick pointers.
-
Shape for progressive disclosure. Apply ref-skill-authoring-standards Progressive disclosure and multi-file skills: keep the always-needed core in SKILL.md and move heavy detail an invocation rarely needs into scoped linked files (its Granularity rule governs how to split them). Outcome: the body is under 500 lines, references stay one level deep, and every linked file is referenced from the body by relative path.
-
Cross-link parents. For each parent skill identified in step 2, edit that skill to add the dispatch line or wrap reference. A skill that no parent invokes is invisible.
-
Add the catalog README row. Edit .agents/skills/README.md: pick the right section table, alphabetical ordering within the section, one-sentence purpose. The purpose itself must satisfy ref-skill-effectiveness Triggerability (it is a second-tier description).
-
Update AGENTS.md if applicable. Apply ref-agents-md-curation Single source of truth and Sync rules.
-
Run skill-review on the new skill. Address every finding before merging.
-
Run uv run pytest tests/agents/test_skills_catalog.py. It enforces the catalog contract mechanically: frontmatter parses as YAML, name matches the directory and is spec-legal, description is a bounded single line, no unexpected keys, the ref-/user-invocable pairing, the README row, and that every section citation and canonical-implementation pointer resolves.
-
Run ./bin/precommit.sh. markdownlint lints the catalog README and every SKILL.md: .markdownlint-cli2.jsonc excludes the .agents/ tree, then re-includes .agents/skills/**/*.md with a trailing positive glob. Skill bodies lint under the relaxed set in .agents/skills/.markdownlint.jsonc, which turns off MD041 so a body may open with a prose callout instead of an H1.
Verification
uv run pytest tests/agents/test_skills_catalog.py covers the mechanical half of this list — frontmatter validity, name and description conformance, the ref-/user-invocable pairing, the README row, section citations, and canonical-implementation pointers. Run it first; the remaining items are judgment calls it cannot make.
- File exists at
.agents/skills/<name>/SKILL.md with valid frontmatter (name, description).
- The body is under 500 lines and every reference is one level deep.
- Any linked file is referenced from the body by a relative-path markdown link (no orphan files); references follow
ref-skill-authoring-standards Referencing files and skills (own files linked, other skills named, code as pointers).
- No section is cited by number —
grep '§' <new-skill>/SKILL.md returns nothing.
- At least one parent skill cross-references the new skill (or, for the rare top-level human workflow, the catalog README is the only reference).
skill-review of the new skill reports no findings under Architecture, Effectiveness, or Structure../bin/precommit.sh returns 0.
