| name | create |
| allowed-tools | Read, Write, Edit, Bash(node:*), Bash(git:*), Bash(npm:*), Bash(ls:*), Bash(mkdir:*), Grep, Glob, TodoWrite, TodoRead, AskUserQuestion, Skill, Task |
| argument-hint | [plugin-name] (optional - will prompt if not provided) |
| description | Create a new plugin for Claude Code marketplace with validation, ADR, and release automation. TRIGGERS - create plugin, new plugin, scaffold plugin |
⛔ Create Plugin — STOP AND READ
DO NOT ACT ON ASSUMPTIONS. Read this file first.
This is a structured workflow command for creating a new plugin in a Claude Code marketplace.
Your FIRST and ONLY action right now: Execute the TodoWrite below.
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
⛔ MANDATORY FIRST ACTION: TodoWrite Initialization
YOUR FIRST ACTION MUST BE the TodoWrite call below.
DO NOT:
- ❌ Create any directories before TodoWrite
- ❌ Read marketplace.json before TodoWrite
- ❌ Ask questions before TodoWrite
- ❌ Jump to any phase without completing Step 0
Step 0.1: Detect Marketplace Root
Before executing TodoWrite, verify you're in a marketplace directory:
/usr/bin/env bash << 'PREFLIGHT_EOF'
if [ -f ".claude-plugin/marketplace.json" ]; then
echo "✅ Marketplace detected: $(jq -r .name .claude-plugin/marketplace.json)"
else
echo "❌ Not a marketplace directory. Run from a marketplace root."
exit 1
fi
PREFLIGHT_EOF
Step 0.2: Execute MANDATORY TodoWrite
Execute TodoWrite NOW with this template:
TodoWrite with todos:
- "[Plugin] Phase 0: Detect marketplace root" | in_progress
- "[Plugin] Phase 0: Interactive prompts (name, category, components)" | pending
- "[Plugin] Phase 0: Confirm plugin doesn't exist" | pending
- "[Plugin] Phase 1: Skill → plugin-structure (scaffold)" | pending
- "[Plugin] Phase 1: Create plugin directory + plugin.json" | pending
- "[Plugin] Phase 1: Skill → implement-plan-preflight (ADR)" | pending
- "[Plugin] Phase 2: Skill → skill-architecture (if has-skills)" | pending
- "[Plugin] Phase 2: Skill → hook-development (if has-hooks)" | pending
- "[Plugin] Phase 2: Skill → command-development (if has-commands)" | pending
- "[Plugin] Phase 2: Skill → agent-development (if has-agents)" | pending
- "[Plugin] Phase 2: Agent → skill-reviewer (if skills created)" | pending
- "[Plugin] Phase 3: Add to marketplace.json" | pending
- "[Plugin] Phase 3: Run validate-plugins.mjs" | pending
- "[Plugin] Phase 3: Skill → code-hardcode-audit" | pending
- "[Plugin] Phase 3: Agent → plugin-validator" | pending
- "[Plugin] Phase 4: Git commit (conventional format)" | pending
- "[Plugin] Phase 4: Push to remote" | pending
- "[Plugin] Phase 4: Skill → semantic-release" | pending
After TodoWrite completes, proceed to Phase 0 section below.
Quick Reference
Skills Invoked (Optimized Sequence)
| Order | Skill | Phase | Purpose | Invocation |
|---|
| 1 | plugin-structure | 1 | Directory & manifest | Skill(plugin-dev:plugin-structure) |
| 2 | implement-plan-preflight | 1 | ADR + Design Spec + Diagrams | Skill(itp:implement-plan-preflight) |
| 3 | skill-architecture | 2 | Create skills (if has-skills) | Skill(plugin-dev:skill-architecture) |
| 4 | hook-development | 2 | Create hooks (if has-hooks) | Skill(plugin-dev:hook-development) |
| 5 | command-development | 2 | Create commands (if has-commands) | Skill(plugin-dev:command-development) |
| 6 | agent-development | 2 | Create agents (if has-agents) | Skill(plugin-dev:agent-development) |
| 7 | code-hardcode-audit | 3 | Quality audit | Skill(itp:code-hardcode-audit) |
| 8 | plugin-validator | 3 | Silent failure audit | Skill(plugin-dev:plugin-validator) |
| 9 | run-full-release | 4 | Run repo's mise release pipeline | Skill(mise:run-full-release) |
Skills EXCLUDED (Redundant)
| Skill | Reason Excluded |
|---|
| plugin-dev:skill-development | Use skill-architecture instead (3x more comprehensive) |
| plugin-dev:plugin-settings | Merged into hook-development |
| itp:adr-graph-easy-architect | Invoked BY implement-plan-preflight (not separately) |
Agents Spawned
| Phase | Agent | Purpose | Invocation |
|---|
| 2 | skill-reviewer | Review skill quality | Task(plugin-dev:skill-reviewer) |
| 3 | plugin-validator | Validate final structure | Task(plugin-dev:plugin-validator) |
File Locations
| Artifact | Path | Notes |
|---|
| Plugin Directory | plugins/{name}/ | Main plugin folder |
| Plugin Manifest | plugins/{name}/plugin.json | Required manifest |
| Plugin README | plugins/{name}/README.md | Documentation |
| Marketplace JSON | .claude-plugin/marketplace.json | Must add plugin entry |
| ADR | docs/adr/YYYY-MM-DD-{name}.md | Created by preflight skill |
| Design Spec | docs/design/YYYY-MM-DD-{name}/spec.md | Created by preflight skill |
Phase 0: Discovery & Validation
Detect marketplace root, gather plugin name/category/components via interactive prompts, confirm the plugin does not already exist.
Detailed steps: Phase 0 Reference
Phase 0 Gate
Phase 1: Scaffold Plugin
- Invoke
Skill(plugin-dev:plugin-structure) -- directory & manifest patterns
- Create plugin directory with component subdirs based on user selections
- Generate
plugin.json using marketplace version
- Invoke
Skill(itp:implement-plan-preflight) -- creates ADR + Design Spec + diagrams
Detailed steps: Phase 1 Reference
Phase 1 Gate
Phase 2: Component Creation (Conditional)
Execute ONLY the skills for components the user selected:
| Component | Skill Invocation | Then |
|---|
| Skills | Skill(plugin-dev:skill-architecture) | Spawn Task(plugin-dev:skill-reviewer) |
| Hooks | Skill(plugin-dev:hook-development) | -- |
| Commands | Skill(plugin-dev:command-development) | -- |
| Agents | Skill(plugin-dev:agent-development) | -- |
Detailed steps: Phase 2 Reference
Phase 2 Gate
Phase 3: Registration & Validation
- Add plugin to
marketplace.json (include hooks field if hooks exist)
- Run
node scripts/validate-plugins.mjs -- expect all-pass
- Invoke
Skill(itp:code-hardcode-audit) -- quality audit
- Run silent failure audit on all hook entry points
- Spawn
Task(plugin-dev:plugin-validator) -- structural validation
Detailed steps: Phase 3 Reference
Phase 3 Gate
Phase 4: Commit & Release
- Stage changes: plugin dir, marketplace.json, ADR, design spec
- Conventional commit:
feat($PLUGIN_NAME): add plugin for [brief description]
- Push to remote
- Invoke
Skill(mise:run-full-release) -- run repo's mise release pipeline for tag, changelog, GitHub release
Detailed steps: Phase 4 Reference
Phase 4 Success Criteria
Troubleshooting
See Troubleshooting Reference for common issues and fixes.
Post-Execution Reflection
After this skill completes, reflect before closing the task:
- Locate yourself. — Find this SKILL.md's canonical path (Glob for this skill's name) before editing. All corrections target THIS file and its sibling references/ — never other documentation.
- What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
- What worked better than expected? — Promote it to recommended practice. Document why.
- What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now.
- Log it. — Every change gets an evolution-log entry with trigger, fix, and evidence.
Do NOT defer. The next invocation inherits whatever you leave behind.
