Skill Add

When the user asks to create a new Claude Code skill, update an existing skill, or rebuild the shipped bundle so the skill changes propagate to Claude Code.

1. Confirm the work is skill-shaped. A skill is task-shaped — a thin index over recipes plus a reference doc, not the recipes themselves. If the doc describes what someone does across many tasks, it is a function, not a skill. See document types§=skill= for the contract.
2. Validate the name against Skill naming conventions. The name must be <domain>-<verb>[-<object>] with the domain prefix and verb taken from the closed registers in that document — named after the action, never a role, artefact, or wrapped command. If the name does not parse, fix the name; if no register entry fits, extending a register is a deliberate act recorded in that document's decision log — never invent a one-off.
3. Check the Skills catalogue for duplication. Search the inventory for an existing skill covering the same action — by prefix, by verb, and by skimming the area headings. If one exists, update it instead of adding a near-duplicate; if the new skill subsumes an old one, fold the old one in and retire it via skill-delete — never delete a skill directory directly; its :ID: may have incoming links across the repository.
4. Identify the recipes the skill will index. Each operational how-to belongs in its own how_do_i_<thing>.org file. If a needed recipe doesn't exist yet, create it first via How do I create a recipe?.
5. Scaffold the skill via compass add skill. Use snake_case for the slug; it becomes the folder name and the Claude Code name: field (doc/llm/skills/<slug>/SKILL.org). See How do I create a new doc? §"New Claude Code skill" for the exact invocation.
6. Fill in the skeleton, in this order:
   • * When to use this skill — one or two sentences.
   • * How to use this skill — numbered steps that mostly link to recipes (do not embed procedural detail).
   • * Recipes — id-links to every recipe the skill indexes.
   • * Reference — id-link to the knowledge document or component model that backs the skill.
7. Check the markdown export block. The name: must match the folder slug and the #+title:' kebab-case stem. The description: is what Claude Code shows in its skill selector; make it crisp and actionable.
8. Verify against the doc contract. The skill-review skill is the canonical checklist — frontmatter, required sections, task-shape, no embedded inventories.
9. Cross-reference the new skill from the relevant function docs. Functions list the skills each cybernetic level invokes (see the * Skills section of each doc/functions/s*.org). A new skill that isn't linked from at least one function is effectively invisible to LLM sessions that load by function. Pick the function(s) the skill belongs to — usually one, often two — and add an id-link with a one-line "when to use" hint.
10. Update the Skills catalogue — add the new skill under the appropriate area heading. This is the canonical inventory.
11. Rebuild the shipped bundle so Claude Code picks up the new or updated skill — see How do I deploy the skills?.

• How do I create a new doc? §"New Claude Code skill" — the scaffold flow.
• How do I create a recipe? — for any new recipes the skill needs to index.
• How do I deploy the skills? — rebuild the bundle.
• How do I refresh org-babel results? — for skills with #+RESULTS: snapshots you want kept fresh.

• Document types§=skill= — the skill contract.
• skill-review skill — the sibling skill that audits a skill against the contract.
• Skills catalogue — the full inventory.
• ores.codegen — the component that hosts the skill template at projects/ores.codegen/library/templates/doc_skill.org.mustache.