---
name: skill-governance
description: Curate the Inspire Courts skill library — decide when a workflow earns a skill, refine/dedupe, retire stale skills, and audit skills against current architecture rules. Keeps the toolkit lean and reviewed. Use periodically, after big architecture changes, or when adding/removing a skill.
argument-hint: "[audit | new <name> | dedupe | retire <name>]"
allowed-tools: Read Edit Write Grep Glob Bash(/opt/homebrew/bin/git *)
---

# Skill governance (the curator)

Project skills live in `.claude/skills/<name>/SKILL.md` and are the canonical,
git-reviewed copies (CLAUDE.md "Skills" section: project copy wins over user-level).
This meta-skill keeps the library **lean + correct + non-redundant** so every other
skill stays trustworthy. Skills encode the architecture rules + standing decisions
into tooling — if they drift from the code, they do harm.

## When a workflow earns a skill (the bar)

Create a skill only when ALL are true:
1. **It repeats** — you've done (or will do) this 3+ times (e.g. porting a web
   section, fixing a facade, scaffolding a screen).
2. **It must follow rules exactly** — there are non-obvious constraints that are
   easy to get wrong (payment gate, no-fabricated-data, nav registration).
3. **It's not already covered** — no existing skill does it (check first; extend
   instead of forking).
4. **It's concrete** — maps to real code paths + files, not generic advice.

If it's a one-off, or pure judgment with no repeatable steps, it does NOT earn a
skill — keep it in DIRECTION/memory instead.

## SKILL.md conventions (enforce on every skill)

- **Frontmatter:** `name` (matches dir), `description` (when-to-use, written so the
  model can route to it), `argument-hint`, `allowed-tools` (least-privilege —
  scope `Bash(...)` to the commands actually needed; no blanket `Bash`). Add
  `disable-model-invocation: true` for deploy-class skills that must be explicit.
- **Body:** grounded in real files (cite exact paths + anchor examples), a
  non-negotiables/rules section, and a done = all true **checklist**. Living
  recipe books (like `motion`) append entries over time.
- **Lean:** prose earns its place. Cut restating CLAUDE.md verbatim — link the rule,
  show the code.

## Refine / dedupe

- **Overlap check:** grep skill bodies for the same files/workflows. If two skills
  cover the same ground, merge into one and delete the weaker, or carve a clear
  boundary in each `description` (e.g. `native-screen-scaffold` = stamp one screen;
  `native-screen-generator` = port a web section using it).
- **Cross-link** related skills by name (scaffold → kit → facade-fix) so the chain
  is discoverable.
- **Tighten `allowed-tools`** to the minimum; widen only with cause.

## Retire stale skills

Retire (delete the dir, note it in the commit) when:
- The workflow no longer exists (the feature/area was removed).
- It's superseded by a better skill (dedupe outcome).
- Its instructions contradict current architecture and can't be salvaged.

Never leave a skill that points at moved/renamed files — fix or retire it.

## Audit skills vs current rules (run periodically)

For each `SKILL.md`:
1. **File-path drift:** every cited path still exists.
   `grep -oE '[a-zA-Z0-9_./-]+\.(swift|ts|tsx|mjs)' .claude/skills/*/SKILL.md`
   then confirm each resolves. (Heads-up: `DesignKit.swift` lives at
   `ios-native/Sources/Features/AdminDesign/`, while the base layer is
   `ios-native/Sources/DesignSystem/DesignSystem.swift` — don't conflate them.)
2. **Rule drift:** the skill's rules still match CLAUDE.md (admin-hub freeze, kit-only
   UI, design tokens, no `dark:`, SWR policy, API guard + manifest, push cooldown)
   and AGENTS.md (read `node_modules/next/dist/docs/` before Next.js code).
3. **Convention drift:** frontmatter complete, `allowed-tools` least-privilege,
   checklist present.
4. **Coverage gaps:** is there a repeated workflow with no skill? Flag it for
   creation (the standing rule: build skills anywhere a workflow repeats).

Produce a short report: OK / fix-needed / retire, with the one-line reason each.

## Library map (keep current)

| Skill | One-line role |
|---|---|
| `native-screen-scaffold` | stamp one native screen correctly first time |
| `native-kit` | use/extend the native component kit (reuse-first) |
| `native-screen-generator` | port a web admin section → native (parity workhorse) |
| `skill-governance` | this meta-skill — curate the library |
| `facade-fix` | wire a "renders but doesn't work" screen end-to-end |
| `data-surfacing` | surface desktop-only/hidden data natively (real data) |
| `ui-wiring` | clickable rows→profile, actionable alerts, nav+search (no orphans) |
| `test-factory` | tests-as-you-build + reusable fixtures/factories |
| `ai-feature` | scaffold an AI feature on the shared prompt/voice lib + safety rails |
| `payment-flow` | build a money flow correctly (Square gate, audit, refund→credit) |
| `observability-auto-fix` | Sentry error → diagnose → fix → ship through the gates |
| `audit`/`cycle`/`improve`/`fix-sweep`/`deploy`/`motion` | baseline website skills |

Update this table whenever a skill is added/retired.

## Checklist

- [ ] New skill cleared the 4-point bar (repeats, rule-bound, non-redundant, concrete).
- [ ] Frontmatter complete + `allowed-tools` least-privilege.
- [ ] Body grounded in real paths with a checklist.
- [ ] No overlap left unmerged; related skills cross-linked.
- [ ] Stale skills retired (not left pointing at dead paths).
- [ ] Library map table updated; committed with a clear message.