sft-scaffold-plugin

Scaffold Plugin

Generate a complete, valid plugin directory structure so you never create plugin files from memory.

When to Use

• Starting a new plugin from scratch
• Adding a new skill to an existing plugin (use the SKILL.md template section only)
• NOT for modifying existing skills — edit them directly

Plugin Directory Template

When asked to create a new plugin, generate this exact structure:

plugins/<plugin-name>/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── <skill-name>/
│       └── SKILL.md
├── CHANGELOG.md

plugin.json

{
  "name": "<plugin-name>",
  "description": "<one-line description of the plugin>",
  "version": "0.1.0"
}

Required fields: name, description, version. Version starts at 0.1.0 for new plugins. The name field MUST match the plugin directory name.

SKILL.md Template

---
name: <skill-name>
description: Use when <triggering conditions only — never summarize the workflow>
---

# <Skill Title>

<Core principle in 1-2 sentences.>

## When to Use

- <Symptom or triggering condition>
- NOT for <explicit exclusion>

## <Core Section>

<Skill content — checklists, patterns, reference material, code examples as appropriate>

## Common Mistakes

- <What goes wrong> → <Fix>

CHANGELOG.md

# Changelog

## [0.1.0] - YYYY-MM-DD

### Added

- <skill-name> skill for <brief purpose>

Optional: hooks/hooks.json

Only create if the plugin needs session hooks. Structure:

{
  "hooks": {
    "<HookType>": [
      {
        "matcher": "<pattern>",
        "hooks": [
          {
            "type": "command",
            "command": "<command>",
            "async": false
          }
        ]
      }
    ]
  }
}

Naming Rules

• Plugin directory name: kebab-case, letters/numbers/hyphens only
• Skill directory name: kebab-case, letters/numbers/hyphens only
• Plugin name in plugin.json MUST match the directory name
• Skill name in SKILL.md frontmatter MUST match the skill directory name

After Scaffolding

1. Run bin/validate-plugin plugins/<plugin-name> to confirm the structure is valid
2. Author the skill content using superpowers:test-driven-development
3. Commit the scaffold before writing skill content — keep scaffolding and content in separate commits

Quick Reference

Field	Location	Rule
plugin name	plugin.json name	Must match directory name
plugin version	plugin.json version	Start at 0.1.0, semver
skill name	SKILL.md frontmatter name	Kebab-case, match directory
skill description	SKILL.md frontmatter description	Starts with "Use when", triggering conditions only
changelog	CHANGELOG.md	Keep a Changelog format, entry for every version