New Plugin

New Plugin Scaffolding

Overview

This skill prevents the 5 deadly sins of plugin creation: forbidden frontmatter fields, verbose command bloat, using disable-model-invocation, workflow descriptions, and redundant name fields.

Core principle: Follow Claude Code plugin architecture from docs/reference/claude-plugin-architecture.md. Observable structure (directories) is easy. Hidden rules (frontmatter, thin wrappers) require discipline.

When to Use

Use when:

• Creating a new plugin from scratch
• User says "scaffold plugin", "create plugin", "new plugin"
• Adding plugin to this marketplace
• Setting up plugin directory structure

Reference: docs/reference/claude-plugin-architecture.md for complete architecture rules.

Scaffolding Workflow

Step 1: Gather Requirements

Ask user:

**Plugin name:** [lowercase-with-hyphens]
**Purpose:** [What problem does this solve?]
**Components needed:**
- [ ] Skills (always - provides logic)
- [ ] Commands (optional - user-facing slash commands)
- [ ] Agents (optional - dispatched by skills)
- [ ] Hooks (optional - lifecycle automation)

**User-facing entry points?** [Which skills need slash commands?]

Validate name:

• Lowercase with hyphens only
• Descriptive but concise
• No conflicts with existing plugins

Step 2: Create Directory Structure

mkdir -p <plugin>/.claude-plugin
mkdir -p <plugin>/skills
# Only if needed:
mkdir -p <plugin>/commands
mkdir -p <plugin>/agents

Rules:

• Skills directory is REQUIRED
• Commands only if user needs slash commands
• Agents only if skills dispatch subagents

Step 3: Create plugin.json

Location: <plugin>/.claude-plugin/plugin.json

Template:

{
  "name": "<plugin-name>",
  "description": "<Brief plugin description>",
  "version": "0.1.0",
  "author": {
    "name": "Dev Coffee",
    "url": "https://github.com/itsdevcoffee"
  },
  "homepage": "https://github.com/itsdevcoffee/devcoffee-agent-skills",
  "repository": "https://github.com/itsdevcoffee/devcoffee-agent-skills",
  "license": "MIT",
  "keywords": ["tag1", "tag2", "tag3"]
}

Fields explained:

• name: Plugin identifier (must match directory name)
• description: Brief summary (< 200 chars)
• version: Semantic version (start at 0.1.0)
• author, homepage, repository, license: Standard metadata
• keywords: Search tags (3-5 recommended)

Step 4: Create First Skill

Location: <plugin>/skills/<skill-name>/SKILL.md

Critical frontmatter rules:

• ONLY 2 fields allowed: name + description
• Max 1024 chars total frontmatter
• Description: 150-200 chars max (trigger matching efficiency)
• Description starts with: "Use when..."
• FORBIDDEN fields: version, framework, status, tools, tags, examples, category, metadata, ANY field that's not name/description

Template:

---
name: <skill-name>
description: Use when [specific triggering conditions - NO workflow summary]
---

# Human-Readable Skill Title

## Overview

[Brief explanation of what this skill does]

## When to Use

- [Triggering condition 1]
- [Triggering condition 2]
- [Triggering condition 3]

When NOT to use:
- [Anti-condition 1]
- [Anti-condition 2]

## Process

[Step-by-step instructions or flowchart]

## Examples

[Code examples, usage scenarios]

## Common Mistakes

[What goes wrong + how to fix]

The Description Trap (CRITICAL):

❌ BAD (workflow summary):

description: Generate unit tests by analyzing code structure, creating test stubs, implementing assertions, and validating coverage

✅ GOOD (triggers only):

description: Use when implementing features/bugfixes and need unit test generation

Why: Descriptions with workflow summaries cause Claude to shortcut and not read the full skill content. Keep descriptions to "Use when..." triggers ONLY.

Step 5: Create Command (If Needed)

Only create commands for user-facing entry points.

Not every skill needs a command. From superpowers analysis:

• 14 skills defined
• 3 commands created
• 11 skills have no autocomplete presence (auto-triggered or called by other skills)

Location: <plugin>/commands/<command-name>.md

Critical frontmatter rules:

• NO name field - filename IS the command name
• NO disable-model-invocation: true - it blocks the Skill tool from invoking commands
• MUST have: description
• Optional: tools, argument-hint

Thin Wrapper Template (7 lines):

---
description: [Brief tooltip for autocomplete]
---

Invoke the <plugin>:<skill-name> skill and follow it exactly as presented to you.

**Arguments received:** $ARGUMENTS

CRITICAL: Commands are thin wrappers. 8 lines, not 62. Full logic lives in the skill.

Commands Are 1:1 Delegators, Not Routers:

❌ WRONG (dispatcher pattern):

Analyze file type and invoke appropriate skill:
- PDF → plugin:pdf
- DOCX → plugin:docx
- XLSX → plugin:xlsx

✅ CORRECT (1:1 delegation):

• Create commands/pdf.md → delegates to plugin:pdf
• Create commands/docx.md → delegates to plugin:docx
• Create commands/xlsx.md → delegates to plugin:xlsx

Why? Dispatchers add complexity, make autocomplete unclear, and violate the thin wrapper pattern. If you need 3 skills, create 3 commands.

Why NO disable-model-invocation: true?

• It blocks the Skill tool from invoking commands
• Breaks all /plugin:command invocations
• See docs/reference/claude-plugin-architecture.md anti-patterns

Step 6: Create Agent (If Needed)

Only create if skill needs to dispatch subagents.

Location: <plugin>/agents/<agent-name>.md

Frontmatter:

---
name: <agent-name>
description: |
  Use this agent when [conditions]

  <example>
  Context: [scenario]
  user: "[message]"
  assistant: "[response]"
  <commentary>[why this agent applies]</commentary>
  </example>

model: inherit
---

You are a [Role]. Your role is to [purpose].

[Detailed system prompt and instructions...]

Required fields: name, description (with examples), model

Step 7: Register in Marketplace

Location: .claude-plugin/marketplace.json

Add entry:

{
  "name": "<plugin-name>",
  "source": "./<plugin>",
  "description": "<Brief description>",
  "version": "0.1.0",
  "author": {
    "name": "Dev Coffee",
    "url": "https://github.com/itsdevcoffee"
  },
  "repository": "https://github.com/itsdevcoffee/devcoffee-agent-skills",
  "keywords": ["tag1", "tag2"],
  "category": "Development Tools",
  "license": "MIT"
}

Verify: Version matches plugin.json

Step 8: Create Documentation

Essential files:

• <plugin>/README.md - User-facing documentation
• <plugin>/LICENSE - MIT license (copy from other plugins)

Optional:

• <plugin>/CHANGELOG.md - If planning releases
• <plugin>/docs/ - Supporting documentation

Step 9: Validate Structure

Run validation:

cd /home/maskkiller/dev-coffee/repos/devcoffee-agent-skills
node scripts/validate-plugins.js

Fix any errors before continuing.

Architecture Checklists

Skill Checklist

• Directory: skills/<skill-name>/SKILL.md (not flat skills/*.md)
• Frontmatter: ONLY name + description (2 fields max)
• Description starts with "Use when..."
• Description has NO workflow summary
• H1 heading is human-readable (doesn't need to match slug)
• Supporting files in same directory (if needed)

Command Checklist

• Location: commands/<command-name>.md
• Frontmatter: NO name field (filename IS the name)
• Frontmatter: NO disable-model-invocation (blocks Skill tool)
• Body: Thin wrapper (7 lines, delegates to skill)
• NOT duplicating skill logic

Plugin Manifest Checklist

• plugin.json exists at .claude-plugin/plugin.json
• Has name, description, version, author, repository, license
• Name matches directory name
• Version uses semantic versioning (MAJOR.MINOR.PATCH)

Marketplace Registration Checklist

• Entry added to .claude-plugin/marketplace.json
• Source path matches plugin directory
• Version matches plugin.json
• Keywords added (3-5 recommended)
• Category assigned

Common Mistakes

Mistake 1: Extra Frontmatter Fields

Symptom: Skill has version, framework, status, tools, tags fields.

Fix: Remove ALL fields except name + description.

Mistake 2: Verbose Command Files

Symptom: Command file is 50+ lines with full documentation.

Fix: Use thin wrapper template (8 lines). Move docs to skill.

Mistake 3: Using disable-model-invocation: true

Symptom: Command frontmatter has disable-model-invocation: true.

Fix: Remove it. It blocks the Skill tool from invoking commands, breaking /plugin:command.

Mistake 4: Workflow in Description

Symptom: Description explains HOW skill works instead of WHEN to use it.

Fix: Rewrite to start with "Use when..." and list triggers only.

Mistake 5: Command Has name Field

Symptom: Command frontmatter includes name: command-name.

Fix: Remove it. Filename IS the command name.

Mistake 6: Flat Skills Directory

Symptom: Skills at skills/skill-name.md instead of skills/skill-name/SKILL.md.

Fix: Create directory per skill, SKILL.md inside.

Mistake 7: Every Skill Has Command

Symptom: 1:1 ratio of skills to commands.

Fix: Only create commands for user-facing entry points. Most skills don't need commands.

Templates Reference

Skill Frontmatter Template

---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions]
---

Command Frontmatter Template

---
description: Brief tooltip text for autocomplete
---

Command Body Template

Invoke the plugin-name:skill-name skill and follow it exactly as presented to you.

**Arguments received:** $ARGUMENTS

Agent Frontmatter Template

---
name: agent-name
description: |
  Use this agent when [conditions]

  <example>
  Context: [scenario]
  user: "[user message]"
  assistant: "[expected response]"
  <commentary>[why agent applies]</commentary>
  </example>

model: inherit
---

Red Flags - STOP Immediately

Further Reading

Complete architecture reference: docs/reference/claude-plugin-architecture.md

Key sections:

• Component Types (commands vs skills vs agents)
• Frontmatter Specifications
• The Thin Wrapper Pattern
• Common Anti-Patterns
• Decision Trees

Research documents:

• docs/research/2026-02-15-superpowers-plugin-structure-analysis.md
• docs/research/2026-02-15-superpowers-naming-and-autocomplete-patterns.md
• docs/research/2026-02-15-superpowers-vs-devcoffee-comparison.md

The Bottom Line

51% of plugin creation is obvious (directories, file locations). 49% requires architecture knowledge (frontmatter rules, thin wrappers, critical fields).

Follow the templates. Reference the architecture doc. Prevent the 5 deadly sins.

Natural instincts mislead:

• "Document everywhere" → Creates bloat
• "Add metadata" → Violates spec
• "Explain thoroughly" → Reduces performance

Templates over intuition. Architecture over assumptions.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.