create-skill

Create a New Skill

Where to place it

Choose the location based on scope — in order of priority:

Priority	Condition	Path
1	User explicitly provided a path	Use that path
2	Skill is tied to a specific component	.ai/Component/{Name}/skills/{skill-name}/SKILL.md
3	Skill is tied to a specific domain	.ai/Domain/{Name}/skills/{skill-name}/SKILL.md
4	Cross-cutting (spans multiple domains/components)	.ai/skills/{skill-name}/SKILL.md

After writing the file:

1. Add a ## Skills section (or entry) to the corresponding CONTEXT.md — root .ai/CONTEXT.md for cross-cutting skills, or .ai/Component/{Name}/CONTEXT.md / .ai/Domain/{Name}/CONTEXT.md for scoped skills. This is the agnostic discovery mechanism for all non-Claude tools.
2. Create a symlink in .claude/skills/ pointing to the skill directory (not the file). The path must be relative. This enables Claude Code auto-discovery.

   cd .claude/skills && ln -s ../../<skill-dir-path-from-repo-root> <skill-name>
   

---

CONTEXT.md vs SKILL.md — no duplication rule

CONTEXT.md owns conventions (rules, patterns, constraints — the "why" and "what"). SKILL.md owns procedures (steps, code templates, checklists — the "how"). Content must live in exactly one place.

	CONTEXT.md	SKILL.md
Contains	Conventions, rules, patterns	Procedures, step-by-step instructions, code templates
Audience	Any AI tool or human	An AI agent executing a specific task
Duplication	Authoritative source — never restated elsewhere	References CONTEXT.md conventions, never restates them

When creating or modifying a skill

For every rule or convention you're about to write in a skill, apply this decision:

1. Read the parent CONTEXT.md first — before writing any content in a skill, read the component (or domain) CONTEXT.md to know what's already documented there
2. Ask: "Does this apply to all skills in this component?" — if yes, it belongs in CONTEXT.md, not the skill. Example: "all handlers use #[AsCommandHandler]" → CONTEXT.md
3. Ask: "Is this specific to this one task?" — if yes, it stays in the skill. Example: "the edit handler checks null before each field" → skill
4. If a convention is missing from CONTEXT.md and should be there — add it to CONTEXT.md first, then reference it from the skill. Never write it only in the skill
5. Reference, don't restate — when a skill needs to remind the reader of a convention, write: See [Component/CONTEXT.md](../../CONTEXT.md#section) for X convention. Do not copy the rule text into the skill