Agent-Skills.md

Agent Skills: Plugin Creator (with Superpowers Enforcement)

This skill should be used when the user asks to 'create a plugin', 'scaffold a plugin', 'set up plugin structure', 'new plugin', 'edit the plugin manifest', 'wire plugin hooks', 'validate plugin structure', or needs plugin-level work spanning multiple components. For creating or editing a single skill (even inside a plugin), use skill-creator instead.

UncategorizedID: edwinhu/workflows/plugin-creator

Repository

edwinhu/workflows
edwinhu
204

Install this agent skill to your local

pnpm dlx add-skill https://github.com/edwinhu/workflows/tree/HEAD/skills/plugin-creator

Skill Files

Browse the full folder contents for plugin-creator.

Download Skill

Loading file tree…

skills/plugin-creator/SKILL.md

Skill Metadata

Name
plugin-creator
Description
"This skill should be used when the user asks to 'create a plugin', 'scaffold a plugin', 'set up plugin structure', 'new plugin', 'edit the plugin manifest', 'wire plugin hooks', 'validate plugin structure', 'audit my plugin's enforcement', or needs plugin-level work spanning multiple components. Use proactively whenever plugin.json, marketplace.json or hooks/hooks.json is being edited, even if the user never says 'plugin'. NEGATIVE ROUTING: never invoke plugin-dev:create-plugin, plugin-dev:plugin-structure or plugin-dev:plugin-validator directly — this skill is the wrapper that adds the enforcement audit they lack. Creating or editing a single skill, even inside a plugin, goes to skill-creator; designing, repairing or auditing a multi-phase workflow goes to workflow-creator."

Plugin Creator (with Superpowers Enforcement)

What this skill carries — grep references/ for any subject the names below miss: !d=${CLAUDE_SKILL_DIR}; command -v skill-toc >/dev/null 2>&1 && exec skill-toc "$d"; s=$HOME/.claude/skills/plugin-utils/bin/skill-toc; [ -x "$s" ] && exec "$s" "$d"; echo "(skill-toc unavailable: references and scripts are NOT listed here — install the plugin-utils plugin, or start a new session so its bin/ reaches PATH)"

Shared references this plugin ships — the plugin-root corpus, indexed so an added document needs no edit here; grep it for any subject the names miss: !r=${CLAUDE_PLUGIN_ROOT}; command -v skill-toc >/dev/null 2>&1 && exec skill-toc "$r" refs; s=$HOME/.claude/skills/plugin-utils/bin/skill-toc; [ -x "$s" ] && exec "$s" "$r" refs; echo "(shared-reference index unavailable: the plugin-root references/ are NOT listed here)"

This skill wraps the built-in plugin-dev:create-plugin with enforcement pattern awareness from the superpowers framework. It adds an enforcement audit layer that the built-in version lacks.

hooks/guards/skill-paths.ts runs after every Edit/Write (in-process, in the plugin's mod) and reports any ${CLAUDE_SKILL_DIR} / ${CLAUDE_PLUGIN_ROOT} reference that resolves to a missing file. hooks/plugin-validate.ts is not registered — its only finding on this repo is a constant symlink warning identical for 91 of 92 firing files. Run manifest validation by hand: claude plugin validate <plugin-dir>.

Process

Step 1: Classify the Plugin

Before drafting, classify what's being created or edited:

| Type | Description | Enforcement Needs | |------|-------------|-------------------| | Full plugin | New plugin with skills, hooks, commands, agents | High — needs enforcement across all components | | Skill addition | Adding a skill to an existing plugin | Medium — needs skill-level enforcement audit | | Hook addition | Adding hooks to an existing plugin | Medium — needs path validation, matcher coverage | | Component edit | Substantial edit to existing plugin component | Medium — needs re-audit of affected enforcement |

Anti-Patterns: Read Before Drafting

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

Step 1b: Check for Mechanical Enforcement Opportunities

Before drafting, identify constraints that should be mechanically enforced rather than prompt-enforced. Four mechanisms are available:

| Mechanism | Resolves at | Use for | |-----------|------------|---------| | ${CLAUDE_SKILL_DIR} | Skill load | Script paths in Bash templates (use directly, never wrap in $()) | | !command`` (bang) | Skill load | Injecting reference file content, environment state | | Scoped hooks (Pre/PostToolUse) | Each tool call | Mechanically checkable constraints (lint, path guards) | | SessionStart hook (once: true) | Session start | Expensive computations (API calls, index builds) — not paths or content |

The principle: if a constraint is mechanically checkable, enforce it with a hook. If it requires judgment, keep it as prompt text.

Step 1c: Run the Checker-Shape Probe

bun ${CLAUDE_SKILL_DIR}/scripts/pc-probe.ts --target <plugin-dir>

Exit 0 clean, 1 findings, 2 argument error, 3 the probe crashed — 2 and 3 are not the same, and neither is a pass. Re-run it after Step 3 and before final validation.

| Output | Do | |---|---| | I1 two engines in one domain | delete one, or make it spawn the other | | I2 two lenses quoting one literal | one lens owns the claim, the other routes to it | | I3 engine with no live caller | wire it or delete it | | I4 computed path does not resolve | fix the level count — it is inert now | | I5 suppression entry matches no label | repoint or delete it; whatever it covered is reported twice | | I6 lens prompt quotes a decided rule | narrow the lens to the undecidable residue, point it at the table through refs | | advisory I7 | the pattern fires on a phrase the corpus recorded as human — check it through ai-tic before shipping | | I8 a <stem>.md beside a <stem>.py | a RULE is markdown a model judges; a CONSTRAINT is code that decides. Never the same rule in two forms — retire the prose, or declare <!-- pc-probe: ignore-two-representations --> when it carries the checker's only written rationale | | I9 checker outside every enumerated directory | move it under a directory a discovery runner globs, or widen the runner. Named-only reach is one rename from silence | | I10 rule with no applies-to: | scope it, or move it out of the checker directory — unscoped, it governs zero workflows | | I11 unknown exemption marker | fix the name; it suppresses nothing while reading as a suppression | | NOT CHECKED note | a check that did not run. Establish it or state it; never read it as a pass | | SUPPRESSED note | a declared exemption was applied. Every one prints on every run |

Step 2: Invoke the Built-in Plugin Creator

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

Skill(skill="plugin-dev:create-plugin")

Follow its full process. The built-in creator handles the workflow — do not reimplement it.

Step 3: Enforcement Audit (After Each Draft)

After writing or revising plugin components (and before final validation), audit against the superpowers enforcement patterns. Read the enforcement checklist:

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

Then score the draft using the appropriate template:

For Plugin Skills

Score against all 12 patterns from the checklist. Focus especially on:

Run the authoring judgement rules over the change first — bun ${CLAUDE_PLUGIN_ROOT}/skills/work/scripts/rule-check.ts --project-dir <repo> --rules ${CLAUDE_PLUGIN_ROOT}/constraints/jev/authoring (exit 2 names each rule at p >= 0.85; exit 1 is Jev unavailable, never a pass). It decides the quality clauses below, so score only presence by hand.

  1. Iron Laws — Does each skill have absolute constraints for high-drift actions? (soft wording: A-SOFT)
  2. Fact Rows (supersedes Rationalization Tables, v5.36.0) — Does each skill state its incident-learned, non-derivable knowledge (numbers, thresholds, named incidents, tool quirks) as declarative bullets with drive-framed consequences? Legacy excuse/reality tables count as present but convert on next touch; never author new ones.
  3. Red Flags + STOP — Are there pattern interrupts for the high-drift wrong actions? (action vs intention: A-FLAG)
  4. Trigger-Only Descriptions — A-DESC
  5. Gate Functions — Does every phase transition have an exit condition? (decidable vs judgement: A-GATE)

For Plugin Hooks

Verify:

  1. Matcher coverage — Do hooks fire on the right tool events?
  2. Path validity — Do hook commands use ${CLAUDE_SKILL_DIR}/../.. (not ${CLAUDE_SKILL_DIR})?
  3. Error handling — Do hooks fail gracefully (non-zero exit blocks the action)?
  4. Scope — Are hooks scoped to skills (frontmatter) or global (plugin.json)?

For Plugin Structure

Verify:

  1. plugin.json — Valid manifest with correct version, name, description
  2. marketplace.json — Version matches plugin.json in all locations
  3. Directory layout — skills/, hooks/, commands/, agents/ as needed
  4. Path portability — No hardcoded absolute paths in any component

Step 4: Reconcile Tensions

Tension resolution: Enforcement patterns go in skill body (not description), implementation code goes in scripts/, names are descriptive but descriptions are trigger-only.

Step 5: Continue Iteration

Return to the built-in plugin creator's process for validation and testing. After each iteration's revision, re-run the enforcement audit (Step 3).

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

References

  • Enforcement checklist: ${CLAUDE_PLUGIN_ROOT}/references/enforcement-checklist.md (loaded above via bang injection)
  • Anti-patterns: ${CLAUDE_PLUGIN_ROOT}/references/creator-anti-patterns.md (loaded above via bang injection)
  • Philosophy: ${CLAUDE_PLUGIN_ROOT}/PHILOSOPHY.md
  • Built-in plugin creator: plugin-dev:create-plugin