Component Registry

PDCA lifecycle management for all Claude Code system components.

Usage

/registry                        # Dashboard — counts + stale warnings
/registry list [type]            # List components (skills, agents, rules, hooks, plugins)
/registry check <name>           # Full detail for one component
/registry update                 # Scan filesystem, add new components, preserve manual fields
/registry scan                   # Integrity check (broken refs, orphans, missing frontmatter)
/registry stale [days]           # Components not tested in N days (default: 30)
/registry deprecate <name>       # Deprecate a skill: move to _archived/, update registry.yaml

Data Store

~/.claude/docs/development/registry.yaml — single YAML file, version-controlled.

Subcommand Details

/registry (default) — Dashboard

Read registry.yaml and produce a summary:

## Component Registry Dashboard

| Type    | Count | Act | Check | Do  | Plan | Stale (>30d) |
| ------- | ----- | --- | ----- | --- | ---- | ------------ |
| Skills  | 38    | 12  | 5     | 8   | 13   | 20           |
| Agents  | 2     | 0   | 1     | 1   | 0    | 2            |
| Rules   | 12    | 8   | 2     | 1   | 1    | 5            |
| Hooks   | 7     | 5   | 1     | 1   | 0    | 3            |
| Plugins | 7     | 4   | 2     | 1   | 0    | 2            |

**Warnings**: 32 components not tested in >30 days.

/registry list [type] — List Components

List all components, optionally filtered by type.

Output format per component:

[pdca_status] name — why (last_manual_test)

Example:

Skills (38):
  [act]   security — Single entry point for security guidance (2026-02-14)
  [act]   review — Unified review dispatcher (2026-02-14)
  [plan]  analytics — DB query helper (never tested)
  ...

Deprecated (2):
  [deprecated] example-skill — Replaced by /unified (deprecated 2026-03-09, remove by 2026-06-07)
  [deprecated] old-helper — No longer needed (deprecated 2026-02-01, OVERDUE: was due 2026-05-02)

Deprecated entries always appear in a separate section at the bottom, never mixed with active components.

/registry check <name> — Component Detail

Find component by name in any type section. Display all fields:

## security (skill)

| Field            | Value                                                                      |
| ---------------- | -------------------------------------------------------------------------- |
| Category         | security                                                                   |
| Why              | Single entry point for stack-specific security guidance                    |
| Intended Impact  | Replace 11 fragmented SOPs with progressive disclosure                     |
| Actual Effect    | Works — tested on app-levero                                               |
| PDCA Status      | act                                                                        |
| Last Manual Test | 2026-02-14                                                                 |
| Depends On       | security-verify                                                            |
| Subcommands      | backend, frontend, database, infrastructure, operations, matrix, checklist |

/registry update — Scan & Sync

1. Scan filesystem for all components:

- skills//SKILL.md (excluding archived) — parse YAML frontmatter - agents/.md (excluding archived) — parse YAML frontmatter - rules/.md — parse YAML frontmatter - hooks/handlers/.py — extract handler functions - settings.json → enabledPlugins — extract enabled plugins

1. For each component found:

- If already in registry.yaml: preserve all manual fields (why, intendedimpact, actualeffect, pdcastatus, lastmanualtest) - If new: add with pdcastatus: plan, lastmanualtest: null, other fields as "TBD"

1. Remove components from the active skills: section of registry.yaml that no longer exist on disk. Do NOT remove entries from the deprecated: section.

1. Write updated registry.yaml

/registry scan — Integrity Check

Check for:

• Orphaned skill dirs: directories in skills/ (excluding _archived/) without SKILL.md
• Missing frontmatter: SKILL.md files without name: in frontmatter
• Broken skill refs: skills that reference non-existent skills in their content
• Agent skill refs: agents listing skills that don't exist
• Stale archived refs: active files referencing _archived/ paths
• Registry drift: components in active sections of registry.yaml that don't exist on disk
• Overdue removals: entries in deprecated: section where removal_date < today

→ Flag as [ACTION REQUIRED] Remove <name> (was due YYYY-MM-DD)

• Upcoming expirations: deprecated entries where removal_date is within 14 days

→ Flag as [WARN] <name> removal in N days (YYYY-MM-DD)

• Archived dir drift: directories in skills/_archived/ that have no corresponding entry in the deprecated: section of registry.yaml — these were moved manually without going through /registry deprecate
• DRY violations: skill SKILL.md files that inline content already covered by a rule in rules/,

without referencing the rule file. Run this check using the following Python snippet:

```python import re from pathlib import Path

rulesdir = Path.home() / ".claude/rules" skillsdir = Path.home() / ".claude/skills"

for skilldir in sorted(skillsdir.iterdir()): if not skilldir.isdir() or skilldir.name.startswith(""): continue skillmd = skilldir / "SKILL.md" if not skillmd.exists(): continue body = skillmd.readtext() for rulefile in sorted(rulesdir.glob("*.md")): m = re.search(r"^#+\s+(.+)", rulefile.readtext(), re.MULTILINE) if not m: continue phrase = m.group(1).strip().lower() if phrase not in body.lower() or rulefile.name in body: continue # Check proximity: if rule filename is within 40 lines, suppress lines = body.split("\n") for i, line in enumerate(lines): if phrase in line.lower(): window = "\n".join(lines[max(0, i - 40) : i + 40]) if rulefile.name not in window: print(f"⚠ DRY: {skilldir.name} inlines '{phrase}' without referencing {rule_file.name}") break ```

Flag as ⚠ DRY: <skill> inlines '<phrase>' without referencing rules/<file>.md. Fix: replace inlined content with See \rules/<file>.md\``.

Output: list of issues found, or "No integrity issues detected."

/registry routing-check — Routing Eval + DRY Audit

Run the routing eval framework against all skill fixtures, then check for DRY violations.

Step 1 — Fixture coverage (structural, $0):

cd ~/.claude/routing-eval
uv run python -m framework.runner --report-dir results/

Reports:

• Skills with no fixture file in routing-eval/fixtures/claude/ → unreachable (no test)
• Skills failing Layer A (keyword match misses or wrong skill matched)
• Ambiguous pairs (two skills competing for the same trigger phrases)
• Pass rate per skill and overall

Step 2 — Usage analytics (from SQLite, $0):

Parse tags and analysis_text fields to identify which skills were invoked. Cross-reference with the registry to surface:

72 skill registrate | 25 usate (30gg) | 47 mai invocate

Flag skills not invoked in 60+ days as candidates for archival.

Step 3 — DRY audit (grep-based, $0):

For each rules/.md, extract key phrases (first ## heading + 3 most distinctive terms). For each skills//SKILL.md, check if those phrases appear inline without a reference to the rule file. Suppress if the rule filename appears within 40 lines of the inline content.

Output format:

⚠ DRY: skill "deploy" contains 12 lines about security scanning but does not reference rules/security-gate.md
⚠ DRY: skill "implementation" inlines TDD steps without referencing rules/tdd.md

Step 4 — 6-check summary (like GBrain check-resolvable):

Output: PASS (6/6) or FAIL (4/6) — see details above.

/registry stale [days] — Stale Components

Filter registry.yaml for components where lastmanualtest is null or older than N days (default: 30).

Output: sorted list, oldest first, with component name, type, and last test date.

/registry deprecate <name> [--grace-days N] — Deprecate a Skill

Formal sunsetting process for a skill. Default grace period: 90 days.

Workflow:

1. Validate <name> exists in the active skills: section of registry.yaml and is not already deprecated
2. Ask for deprecation_reason if not supplied as --reason "string"
3. Move skills/<name>/ directory to skills/_archived/<name>/
4. Prepend standard deprecation banner to skills/_archived/<name>/SKILL.md:

``markdown > DEPRECATED: <deprecationreason>. Will be removed on <removaldate>. ``

1. Remove <name> from active skills: section in registry.yaml
2. Add entry to deprecated: section:

``yaml <name>: type: skill deprecationdate: <today> removaldate: <today + gracedays> deprecationreason: "<reason>" ``

1. Print summary and suggest CHANGELOG entry:

`` chore(registry): deprecate <name> — <reason> ``

Example:

/registry deprecate prp-generator --reason "Merged into /story prp subcommand" --grace-days 60

PDCA Status Meanings

Lifecycle

plan → do → check → act ─┬→ deprecated → [removed from registry]
                          └→ (stays active, re-enters plan if issue found)

Deprecated lifecycle:
  /registry deprecate <name>
    → skill dir moves to skills/_archived/<name>/
    → deprecation_date set, removal_date = deprecation_date + grace_days
    → /registry scan flags [WARN] when within 14 days
    → /registry scan flags [ACTION REQUIRED] when past removal_date

Workflow

Typical PDCA cycle for a component:

1. Create/modify component → set pdca_status: do
2. Implementation complete → set pdca_status: check
3. Manual test passes → set pdcastatus: act, update lastmanual_test
4. Issue found → set pdcastatus: plan, document issue in actualeffect
5. Component replaced/obsolete → run /registry deprecate <name>