Skill Add

Table of Contents

1. When to use this skill

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.

2. How to use this skill

  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 System, not a skill. See document types§=skill= for the contract.
  2. Validate the name against Skill naming conventions. Every skill this project owns carries the compass- prefix, and the second segment says which regulatory function it offers: principle- for a stance, method- for a sequence of phases, a domain for an action. An action's domain and verb come 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. Unsure which kind of thing you are naming? Take the first match in that document's placement procedure.
  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 compass-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. Set #+level:. It is mandatory on every skill: it is what lets a session's declared System attenuate the catalogue. Take the value from the level register in Skill naming conventions — cross when the skill applies at every level.
  7. 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.
  8. 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.
  9. Verify against the doc contract. The compass-skill-review skill is the canonical checklist — frontmatter, required sections, task-shape, no embedded inventories.
  10. Cross-reference the new skill from the relevant System docs. Each System lists the skills its cybernetic level invokes (see the * Skills section of each doc/systems/s*.org). A new skill that isn't linked from at least one System is effectively invisible to LLM sessions that load by System. Pick the System or Systems the skill belongs to, usually one and often two, and add an id-link with a one-line "when to use" hint.
  11. Update the Skills catalogue — add the new skill under the appropriate area heading. This is the canonical inventory.
  12. Rebuild the shipped bundle so Claude Code picks up the new or updated skill — see How do I deploy the skills?.

3. Recipes

4. Reference

Emacs 29.3 (Org mode 9.6.15)