Skill Creator (with Superpowers Enforcement)

This skill wraps the built-in skill-creator:skill-creator with enforcement pattern awareness from the superpowers framework. It adds an enforcement audit layer to the skill-creator's draft-test-iterate loop.

When This Skill Applies

All skill creation and improvement work. This skill loads instead of the built-in skill-creator because it adds enforcement awareness that the built-in version lacks.

Process

Step 1: Classify the Skill

Before drafting, classify the skill being created:

This classification determines how much enforcement audit to apply after each draft.

Anti-Patterns: Read Before Drafting

!cat ${CLAUDE_SKILL_DIR}/../../references/creator-anti-patterns.md

Step 1b: Check for Mechanical Enforcement Opportunities

Before drafting, identify what should be mechanically enforced rather than prompt-enforced. Four mechanisms are available, each resolving at a different time:

${CLAUDE_SKILL_DIR} — Script Path References

Use directly in Bash command templates — substituted at skill load time to the full absolute path:

# ✅ CORRECT: Variable substituted at load time, Claude sees literal path
python3 "${CLAUDE_SKILL_DIR}/scripts/my_script.py" --arg value

# ❌ WRONG: Broken $() subshell — executes script with no args, captures garbage
SCRIPT=$(${CLAUDE_SKILL_DIR}/scripts/my_script.py) && python3 "$SCRIPT" --arg value

The $() indirection pattern is a common mistake. It tries to execute the script in a subshell and capture its stdout — but scripts require arguments and fail with no args, leaving the variable empty.

Bang-Backtick Injection (!command``)

Bangs run a shell command at skill load time and inline the stdout into the prompt text. Use them to inject content, not paths:

Bangs only work in top-level skills loaded via Skill(). Internal skills loaded via Read() should use direct Read() instructions.

Scoped Hooks (PreToolUse / PostToolUse)

Hooks in skill frontmatter fire only while the skill is active — automatically cleaned up when the skill finishes:

hooks:
  PreToolUse:
    - matcher: "Write"
      hooks:
        - type: command
          command: "python3 $HOME/.claude/skills/my-skill/hooks/guard.py"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/lint.py"

SessionStart Hooks for Expensive Resolutions

For values that genuinely require expensive computation (API calls, multi-step searches, environment probes) and are stable for the session:

hooks:
  SessionStart:
    - hooks:
        - type: command
          command: "expensive-api-call --query env > .planning/CACHED_VALUE"
          once: true

Then instruct the skill to read from .planning/CACHED_VALUE. Do NOT use for path resolution (${CLAUDE_SKILL_DIR}) or content injection (bangs) — those are free at load time. See references/sessionstart-caching.md.

The principle: if a constraint is mechanically checkable, enforce it with a hook. If it requires judgment or motivation, keep it as prompt text. Hooks cost zero tokens and can't be rationalized away.

Step 2: Invoke the Built-in Skill Creator

Use the Skill tool to invoke the built-in skill-creator:

Skill(skill="skill-creator:skill-creator")

Follow its full process: capture intent, interview, draft SKILL.md, write test cases, run evals, iterate. The built-in skill-creator handles the eval loop — do not reimplement it.

Step 3: Enforcement Audit (After Each Draft)

After writing or revising the skill draft (and before running test cases), audit it against the superpowers enforcement patterns. Read the enforcement checklist:

!cat ${CLAUDE_SKILL_DIR}/../../references/enforcement-checklist.md

Then score the draft using the process below.

For Workflow Skills (High Enforcement)

Score against all 12 patterns. Use the scoring template from the checklist. Focus on:

1. Iron Laws — Does the skill have absolute constraints for high-drift actions? Are they wrapped in <EXTREMELY-IMPORTANT> tags with strong framing? If they use soft language ("try to", "should", "consider"), they will be ignored — rewrite with action-masking language.

2. Rationalization Tables — Does the skill preempt the agent's excuses? The table must contain actual excuses the agent generates, not hypothetical ones. Observe failure modes in test runs, then add entries.

3. Red Flags + STOP — Are there pattern interrupts for observable wrong actions? Must target actions ("About to X"), not intentions ("Thinking about X").

4. Gate Functions — Does every phase transition have a verifiable exit condition? "Quality is sufficient" is not a gate. "File X contains string Y" is a gate.

5. Trigger-Only Descriptions — Does the description contain ONLY trigger phrases? If it contains a process summary, the agent will follow the short description instead of reading the body. This is the single most common skill design mistake.

6. Drive-Aligned Framing — Do verification steps use helpfulness-first framing? "Skipping X is NOT HELPFUL — [concrete user harm]" is stronger than "incorrect" or "premature" because it targets the model's strongest drive.

7. Skill Dependencies — Does each phase explicitly read and invoke the next phase? Without explicit chaining, the agent will stop and wait.

8. No Pause Between Tasks — Does the skill prevent "should I continue?" between tasks?

8b. Flat Agent Dispatch — If the skill spawns agents that perform multiple checks or tasks, does the skill spawn them ALL directly in parallel? Or does it spawn a "dispatcher" agent that spawns its own sub-agents? Three-layer delegation (skill → agent → sub-agents) fails because sub-sub-agent results don't reliably return. The orchestrator must spawn all agents directly. See workflow-creator's Iron Law of Flat Dispatch.

9. Delete & Restart — For protocol violations, does the skill mandate deletion of contaminated work?

10. Staged Review Loops — Do implementation sections have review loops with iteration limits?

11. Flowcharts as Spec — For complex processes, is there an ASCII diagram that serves as the authoritative definition?

Critical gaps = High-drift action + Absent/Weak enforcement. Fix these before running evals.

For Tool Skills (Medium Enforcement)

Score against patterns 2, 3, 5, and 10:

• Rationalization Tables — What are common misuse patterns? (e.g., using the wrong API endpoint, skipping authentication)
• Red Flags + STOP — What wrong actions can the agent take? (e.g., calling a destructive API without confirmation)
• Trigger-Only Descriptions — Keep description to triggers only
• Staged Review Loops — For multi-step tool interactions, add review after each step

For Knowledge Skills (Low Enforcement)

Score against pattern 5 only:

• Trigger-Only Descriptions — This is the most important pattern for knowledge skills. If the description summarizes the knowledge, the agent reads the summary instead of the full body.

Step 4: Reconcile Tensions

The built-in skill-creator's writing advice and superpowers enforcement patterns have a genuine tension:

When the built-in skill-creator suggests removing enforcement patterns because they're "not pulling their weight" or are "oppressively constrictive MUSTs," push back if the pattern addresses a real observed failure mode. The test: did an agent actually take the shortcut this pattern prevents? If yes, keep it.

Step 5: Continue the Eval Loop

Return to the built-in skill-creator's process for running test cases, grading, and iterating. After each iteration's skill revision, re-run the enforcement audit (Step 3) on the updated draft.

During the eval loop, watch for enforcement iteration signals (see "Enforcement Iteration Signals" in the anti-patterns reference loaded above).

References

• Enforcement checklist: references/enforcement-checklist.md (in plugin root) — Full 12-pattern reference with templates. Discover via: ${CLAUDE_SKILL_DIR}/../../references/enforcement-checklist.md
• Philosophy: PHILOSOPHY.md (in plugin root) — Three pillars (phased decomposition, deterministic gates, adversarial review). Discover via: ${CLAUDE_SKILL_DIR}/../../PHILOSOPHY.md
• Built-in skill-creator: Handles the eval loop (draft → test → grade → iterate → description optimization)