Agent-Skills.md

Agent Skills: Component Registry

Query, update, and audit the registry of all Claude Code components (skills, agents, rules, hooks, plugins) with PDCA lifecycle tracking. Use when listing/inspecting components, finding stale ones, or registering new ones. Trigger on "list skills", "component registry", "what skills exist", "stale skills", "/registry".

UncategorizedID: matteocervelli/llms/registry

Repository

matteocervelli/llms
matteocervelliLicense: MIT
252

Install this agent skill to your local

pnpm dlx add-skill https://github.com/matteocervelli/llms/tree/HEAD/.codex/skills/registry

Skill Files

Browse the full folder contents for registry.

Download Skill

Loading file tree…

.codex/skills/registry/SKILL.md

Skill Metadata

Name
registry
Description
Query, update, and audit the registry of all Claude Code components (skills, agents, rules, hooks, plugins) with PDCA lifecycle tracking. Use when listing/inspecting components, finding stale ones, or registering new ones. Trigger on "list skills", "component registry", "what skills exist", "stale skills", "/registry".

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

  2. For each component found:

    • If already in registry.yaml: preserve all manual fields (why, intended_impact, actual_effect, pdca_status, last_manual_test)
    • If new: add with pdca_status: plan, last_manual_test: null, other fields as "TBD"

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

  4. 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:

    import re
from pathlib import Path

rules_dir = Path.home() / ".claude/rules"
skills_dir = Path.home() / ".claude/skills"

for skill_dir in sorted(skills_dir.iterdir()):
    if not skill_dir.is_dir() or skill_dir.name.startswith("_"):
        continue
    skill_md = skill_dir / "SKILL.md"
    if not skill_md.exists():
        continue
    body = skill_md.read_text()
    for rule_file in sorted(rules_dir.glob("*.md")):
        m = re.search(r"^#+\s+(.+)", rule_file.read_text(), re.MULTILINE)
        if not m:
            continue
        phrase = m.group(1).strip().lower()
        if phrase not in body.lower() or rule_file.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 rule_file.name not in window:
                    print(f"⚠ DRY: {skill_dir.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):

| Check | What | Pass condition | | ------------------- | ----------------------------------------------- | -------------- | | 1 Reachability | Every skill has a fixture file | 0 missing | | 2 File existence | Every fixture references a real SKILL.md | 0 broken | | 3 MECE overlap | No two skills dominate the same trigger | 0 collisions | | 4 MECE gap | No fixture left unmatched by any skill | 0 gaps | | 5 DRY violations | No inlined rule content | 0 violations | | 6 Frontmatter audit | All SKILL.md have name + description ≤200 chars | 0 malformed |

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

/registry stale [days] — Stale Components

Filter registry.yaml for components where last_manual_test 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: 
    > **DEPRECATED**: <deprecation_reason>. Will be removed on <removal_date>.
  5. Remove <name> from active skills: section in registry.yaml
  6. Add entry to deprecated: section: 
    <name>:
  type: skill
  deprecation_date: <today>
  removal_date: <today + grace_days>
  deprecation_reason: "<reason>"
  7. 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

| Status | Meaning | | ------------ | ------------------------------------------------------------------------- | | plan | Component exists but hasn't been validated. Needs review. | | do | Being actively developed or modified. | | check | Implementation done, needs testing/validation. | | act | Tested, validated, working in production. Monitoring. | | deprecated | Replaced or obsolete. Moved to _archived/. Grace period before removal. |

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 pdca_status: act, update last_manual_test
  4. Issue found → set pdca_status: plan, document issue in actual_effect
  5. Component replaced/obsolete → run /registry deprecate <name>