skill-governance

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.