Skill Review Skill

When you need to confirm one or more existing skills still match the doc contract — periodic audit, after a codebase change that may have invalidated their instructions, or before adding a new skill that might overlap.

1. Get the current list of skills from the canonical source — never maintain it in this file. The Skills catalogue groups skills by area. For a flat, scriptable view:

   ./projects/ores.compass/compass.sh list --type skill
   

2. Inspect each skill's metadata via the doc tools:

   ./projects/ores.compass/compass.sh show <uuid-prefix>
   

   This prints the skill's blurb, outgoing links (the recipes / reference docs it depends on), and incoming links (other skills that link to it).

3. Check each skill against the doc contract. The contract is the authoritative source — read skill in document types; the items below are the ones to focus on during review:
   • Frontmatter: :ID:, #+title:, #+description:, #+type: skill, #+level: cross, #+filetags:, #+created: / #+updated:.
   • Markdown export block with name: / description: / license: (Claude Code metadata, tangled into the shipped bundle).
   • Required sections, in order: * When to use this skill, * How to use this skill, * Recipes, * Reference, * Artefacts :noexport: containing the licence tangle.
4. Check that the skill is task-shaped, not role-shaped. A skill is how to do a unit of work. If the doc describes what someone does across many tasks, it is a function, not a skill — flag for re-homing.
5. Check that procedural detail lives in recipes, not in the skill. A skill is a thin index. Detailed commands, examples, and step-by-step procedures belong in doc/recipes/<topic>/. If you see embedded shell sequences, cmake --build invocations, or templates inside the skill, replace them with id-links to the matching recipe.
6. Check that the skill does not embed an inventory of other skills. Use id-links to the Skills catalogue instead — embedded lists go stale.
7. Spot-check the linked recipes and references still exist. The compass show output will flag broken [[id:...]] as BROKEN.
8. File findings. Either:
   • Open a task in the current sprint for each fix-shaped finding,
   • Open a capture in =next/=|=deferred for larger restructures, or
   • Apply the fix directly when it's a one-line correction.
9. Check each name against Skill naming conventions. Every name must parse as <domain>-<verb>[-<object>] with both parts in the registers; flag roles, artefact names, and wrapped-command names.
10. Build the deletion list. Collect every skill that is a near-duplicate, a dissolved role, reference-only (no executable steps), or superseded. For each entry record the reason and the successor (skill, knowledge doc, or none).
11. Retire each entry via skill-delete — one invocation per skill, so incoming links are re-pointed, the catalogue's Retired section is updated, and the deployed copy is purged. Never delete skill directories directly from a review.

• How do I find docs matching a pattern? — list the skills.
• How do I show a doc by UUID? — inspect one skill's metadata.
• How do I create a new doc?§"New Claude Code skill" — the scaffold the contract is built around.

• Document types§=skill= — the doc contract every skill satisfies.
• Skills catalogue — canonical inventory of all skills.