catalyst-update-skill-registry

name: catalyst-update-skill-registry description: > Regenerates the project's skill catalog at .claude/skills/REGISTRY.md by scanning every SKILL.md under .claude/skills/ and grouping the entries by type. Trigger: IMMEDIATELY after creating, editing, deleting, or renaming ANY SKILL.md in the project — even if the user does not ask explicitly — because a stale registry lies to the next Claude and breaks skill discovery. Also trigger whenever the user mentions "update the registry", "regenerate the catalog", "skill catalog", "skill index", or anything related to the inventory of skills, EVEN IF they don't use the word "registry". license: MIT metadata: author: aurora version: '1.0' auto_invoke: 'After creating/editing/deleting a SKILL.md; when user asks to update the skill registry' allowed-tools: Read, Edit, Write, Glob, Grep, Bash

When to Use

• You have just created a new SKILL.md under .claude/skills/
• You have just edited the name, description, or trigger of an existing SKILL.md
• You have just deleted or renamed a skill
• The user asks to "update the registry", "regenerate the skill catalog", or similar

STOP if you are not sure which skills changed. Scan first, do not assume.

Critical Patterns

1. Type-first taxonomy

All skills live under a single location (.claude/skills/), so the REGISTRY is organized by type only. Type comes from the skill's function, not its filename prefix.

Do NOT change the taxonomy without reason. If a new skill does not fit an existing subcategory, STOP and ask the user before inventing a new one. Subcategories are UX for humans, and arbitrary ones fragment the mental model.

2. Exclude this skill from self-processing

catalyst-update-skill-registry must appear under the Meta subcategory, but do NOT self-duplicate logic by scanning itself multiple times. Include it exactly once.

3. Trigger formatting

Extract from the frontmatter description the text after Trigger: if present. Otherwise, use the full description text. Keep it concise (1-2 lines).

4. Preserve the preamble

The REGISTRY preamble (title, "How to use", sync rule) is preserved across regenerations. Only the tables change.

Procedure

Step 1 — Scan SKILL.md files

Use Glob on .claude/skills/*/SKILL.md and Read each file. Equivalent shell survey:

for f in .claude/skills/*/SKILL.md; do
  echo "=== $f ==="
  awk '/^---$/{c++; next} c==1{print}' "$f"
done

Extract for each skill:

• name (from frontmatter)
• description (from frontmatter, the narrative part)
• Trigger (the text after Trigger: inside description)

Step 2 — Classify

For each skill, pick a subcategory from the table in Critical Patterns §1. Use the skill's function, not its filename prefix. If a skill does not fit, STOP and ask the user before inventing a new subcategory.

Step 3 — Write REGISTRY.md

Write .claude/skills/REGISTRY.md using exactly this template (preserving the preamble):

# Skill Registry — Aurora Catalyst Docs

A navigable catalog of the project's skills, organized by **type**. Each `SKILL.md` is the
source of truth — this file is only the index.

**Sync rule**: after creating, editing, or deleting any skill, regenerate this file so it
reflects the real state.

## How to use this registry

1. Identify the category that matches your task (docs automation, openspec workflow, meta)
2. Locate the applicable skill under that heading
3. Read the `SKILL.md` BEFORE writing code
4. Multiple skills may apply at once — read them all and combine their rules

---

## Docs automation

Author content under `src/content/docs/` from external sources (sibling-repo archives,
auto-generated reference, changelog entries).

| Skill | Trigger | Path |
| --- | --- | --- |
| `{name}` | {trigger} | `.claude/skills/{name}/SKILL.md` |

---

## Workflow — OpenSpec SDD

Drive the openspec propose / apply / archive / explore loop.

| Skill | Trigger | Path |
| --- | --- | --- |
| `{name}` | {trigger} | `.claude/skills/{name}/SKILL.md` |

---

## Meta

Operate on the skill ecosystem itself.

| Skill | Trigger | Path |
| --- | --- | --- |
| `{name}` | {trigger} | `.claude/skills/{name}/SKILL.md` |

Step 4 — Verify

After writing the REGISTRY:

1. Count SKILL.md files: eza .claude/skills/ | wc -l
2. Count entries in the generated REGISTRY (one per row)
3. The numbers must match (each existing SKILL.md = one entry in the registry)
4. If there is a mismatch, investigate before marking the task complete

Rules

• Keep a subcategory section even when it feels redundant, unless a skill has actually disappeared from the filesystem. Removing a section may delete navigational context that other entries still lean on.
• Do not invent new subcategories on the fly. If a new skill doesn't fit an existing one, ask the user first — subcategories are UX for humans, and arbitrary ones fragment the mental model.
• Preserve the preamble verbatim. It explains the usage flow; rewriting it every regeneration is churn with no reader benefit.
• Keep subcategories in stable order (Docs automation → Workflow — OpenSpec SDD → Meta) and skills alphabetical within each subcategory. This avoids diff noise when entries are added.

Commands

# List every skill
eza .claude/skills/

# Extract frontmatter from every SKILL.md
for f in .claude/skills/*/SKILL.md; do
  echo "=== $f ==="
  awk '/^---$/{c++; next} c==1{print}' "$f"
done