---

name: harden-skill description: Audits and rewrites a single Claude skill file applying three principles — correct visibility flags (disable-model-invocation, user-invocable), deterministic steps (replace AI-interpretable fixed ops with scripts), and self-verification (generate AND verify output). Trigger when the user says "harden skill X", "apply audit to X", "rewrite X with visibility flags", or "improve skill X". Outputs the rewritten skill with a changelog.

/harden-skill — Single-Skill Audit & Rewrite

Takes one skill, applies the three-axis audit, and produces a hardened rewrite with a changelog of every change and why.

Composability

• Input: A skill name (e.g. researcher, plan, /my-custom-skill)
• Output: Rewritten skill file + changelog — ready to commit
• Uses: backend/scripts/capability-map.sh for checking if a deterministic script already exists
• Part of: A periodic skill maintenance cycle — run on any skill added before these principles existed

---

STEP 1 — Read the Skill

Read the full .claude/commands/[skill-name].md file.

Then read:

bash backend/scripts/capability-map.sh

This shows what scripts already exist as Level 3 resources.

---

STEP 2 — Axis 1: Visibility Audit

Check: disable-model-invocation

Does this skill have side effects that should only be user-triggered?

Side effects that require disable-model-invocation: true:

• Commits, pushes, or merges
• Deploys or infrastructure changes
• Sending messages or notifications
• Any action that's hard to reverse

If yes and the flag is missing → add it.

Check: user-invocable

Is this skill pure background knowledge that users would never /run directly?

Background knowledge that requires user-invocable: false:

• Architecture reference sheets (file maps, env vars, stack descriptions)
• Constraint lookup tables
• Context injected into Claude automatically when relevant

If yes and the flag is missing → add it.

Check: Level 1 metadata quality

Does the frontmatter description field contain:

• Precise trigger language — exact phrases that should fire this skill
• What it produces — one-line output description
• What it's NOT for — distinguishes from similar skills

If the description is vague → rewrite it to be precise.

---

STEP 3 — Axis 2: Deterministic Steps Audit

Scan every step in the skill body for AI doing something that is actually a fixed, repeatable operation:

| Pattern to flag | Replace with | |---|---| | "Run the tests and check if they pass" | bash backend/scripts/ship-gate.sh | | "Check for SQL string interpolation" | bash backend/scripts/check-sql-injection.sh | | "Is the server alive?" | bash backend/scripts/health-check.sh | | "What's the next migration number?" | bash backend/scripts/next-migration.sh | | "List all existing routes and services" | bash backend/scripts/capability-map.sh | | "Check how many connections the pool is using" | A script that queries pg_stat_activity | | Any lookup of a static fact from a file | Read the file directly or script it |

For each flagged step:

• Confirm a script already exists (from capability-map.sh output) or flag that a new one is needed
• Replace the step with the script call + a note that the AI should interpret the exit code / output

---

STEP 4 — Axis 3: Composability Audit

Check:

• Does the skill declare its Input (what it receives) and Output (what it produces)?
• Does it name the next skill in the chain (what to run after this)?
• Does it duplicate logic from another skill — checklists, formats, or knowledge already in another .claude/commands/ file?
  • If yes → replace the duplicated section with "see [skill-name]" and a pointer

---

STEP 5 — Self-Verification Audit

Does the skill have a self-check block that runs before outputting its final result?

A self-check must verify:

• Every required step was completed (not assumed)
• Scripts were actually run (not skipped)
• Output is internally consistent (e.g. verdict matches findings)
• The recommended next step is concrete (names a skill + input string)

If the self-check is missing → add one, placed immediately before the output format section.

---

STEP 6 — Produce the Rewrite

Apply all findings from Steps 2–5 to produce the rewritten skill file.

Self-Check (run before outputting rewrite)

• [ ] Frontmatter has name, description, and correct visibility flags
• [ ] Every deterministic step identified in Step 3 is replaced with a script call
• [ ] Composability section declares Input, Output, and next skill in chain
• [ ] Self-check block exists and covers all required fields
• [ ] No logic was removed that was legitimately AI judgment
• [ ] No changes made that weren't flagged in Steps 2–5 (surgical edits only)

---

Output Format

## Skill Audit: [skill-name]

### Findings
| Axis | Issue | Severity |
|---|---|---|
| Visibility | [e.g. "disable-model-invocation missing — skill orchestrates commits"] | High / Medium / Low |
| Deterministic | [e.g. "Phase 3 asks AI to check if tests pass — should call ship-gate.sh"] | High / Medium / Low |
| Composability | [e.g. "Duplicates security checklist from security-and-hardening.md"] | High / Medium / Low |
| Self-verification | [e.g. "No self-check before verdict output"] | High / Medium / Low |

### Changelog
- **[line/section]:** [what changed] — [why]
- **[line/section]:** [what changed] — [why]

### Rewritten Skill
[Full rewritten .md content]

---

Ground Rules

• Surgical edits only. Don't restructure the whole skill if only the frontmatter needs changing.
• Never remove AI judgment. Only replace steps that are actually deterministic.
• If a needed script doesn't exist — flag it as a finding but don't invent the script call. Create the script separately first.
• One skill per run. Multiple skills = multiple runs.