/creating-plugins

name: creating-plugins
description: Scaffolds a new Claude Code plugin package with manifest, skills, agents, and marketplace entry. Use when creating a new Claude Code plugin package. Use when user says "create plugin", "new plugin", "scaffold plugin", "plugin template".

Creating Plugins

Overview

**Creating plugins IS scaffolding a distributable agent engineering package.**

A plugin is the distribution unit for agent engineering — it bundles skills, commands, agents, hooks, MCP servers, and LSP configs into a single installable package. Plugins are not just "skill containers" — they can provide complete workflows with automated enforcement (hooks), external tool access (MCP), and language intelligence (LSP).

**Core principle:** Plugins are reusable across projects. Keep them focused and well-documented.

Task Initialization (MANDATORY)

Follow [task initialization protocol](../../references/task-initialization.md).

**Tasks:** 1. Gather requirements 2. Create directory structure 3. Generate plugin manifest 4. Create initial skill 5. Write README 6. Document version bump locations in plugin CLAUDE.md 7. Test installation

Announce: "Created 7 tasks. Starting execution..."

Task 1: Gather Requirements

**Goal:** Understand what the plugin should contain.

**Questions to ask:**

• What is the plugin name? (kebab-case)
• What capability does it provide?
• What skills should it include?
• Who is the author?

**Naming rules:**

• Kebab-case only: `my-plugin`
• Avoid: `helper`, `utils`, `anthropic`, `claude`
• Max 64 characters

**Verification:** Can state plugin name and purpose in one sentence.

Task 2: Create Directory Structure

**Goal:** Scaffold the plugin directory.

Plugin Structure

<plugin-name>/
├── .claude-plugin/
│   └── plugin.json      # Manifest
├── skills/              # Capabilities (auto-discovered)
│   └── <skill-name>/
│       ├── SKILL.md
│       └── references/  # On-demand loaded docs
├── commands/            # Slash command aliases (auto-discovered)
│   └── <command>.md
├── agents/              # Subagent definitions (auto-discovered)
│   └── <agent>.md
├── hooks/               # Lifecycle hooks (auto-discovered)
│   └── hooks.json
├── .mcp.json            # MCP server configs (auto-discovered)
├── .lsp.json            # Language server configs (auto-discovered)
└── README.md

Key Variables for Plugin Skills

**In SKILL.md content (substituted at runtime):**

| Variable | Purpose | |----------|---------| | `${CLAUDE_SKILL_DIR}` | This skill's directory — use to reference bundled scripts/data regardless of CWD | | `${CLAUDE_SESSION_ID}` | Current session ID | | `$ARGUMENTS` / `$N` | Arguments passed when invoking the skill |

**In hooks/hooks.json only — NOT available in SKILL.md content:**

| Variable | Purpose | |----------|---------| | `${CLAUDE_PLUGIN_ROOT}` | Plugin install directory (changes on update — do not write here) | | `${CLAUDE_PLUGIN_DATA}` | Persistent data directory that survives updates (`~/.claude/plugins/data/{id}/`) |

Skills can also inject live data using shell commands (execute as preprocessing before Claude sees content). See [references/plugin-templates.md](references/plugin-templates.md) for exact shell-injection syntax (inline form, plugin-internal file form, multi-line fenced form, and PowerShell setup).

**If the plugin includes scripts or hooks:** Read [cross-platform-scripts.md](../../references/cross-platform-scripts.md) for mandatory cross-platform rules (paths, shell commands, line endings).

**Verification:** Directory structure created with all required paths.

Task 3: Generate Plugin Manifest

**Goal:** Create the plugin.json manifest file.

**Important:** Read [references/plugin-templates.md](references/plugin-templates.md) for manifest format, required fields, and marketplace structure.

**Verification:** plugin.json is valid JSON with required fields.

Task 4: Create Initial Skill

**Goal:** Create the first skill using the writing-skills workflow.

**Important:** Invoke the `writing-skills` skill.

Do not write SKILL.md directly. The writing-skills skill ensures:

• Proper frontmatter format
• TDD baseline testing
• Quality review via skill-reviewer

**Verification:** Initial skill created and passes skill-reviewer.

Task 5: Write README

**Goal:** Document the plugin for users.

**Important:** Read [references/plugin-templates.md](references/plugin-templates.md) for README template.

**Verification:** README has installation instructions and skill list.

Task 6: Document Version Bump Locations in Plugin CLAUDE.md

**Goal:** Plugin root `CLAUDE.md` lists every file containing this plugin's version string, so Claude can sync them correctly regardless of whether release automation is in place.

**Why:** Plugin has 3+ version fields (plugin.json, marketplace.json entry, README headers). Release-automation scripts (release-please, semantic-release) fail in various ways — cross-package path limits, marker scope collisions, CI permission issues. CLAUDE.md is authoritative session guidance; when a commit bumps version, Claude reads it and syncs every location. Scripts remain optional — not required by this skill.

**Action:** 1. Enumerate every file containing this plugin's version string (typically `plugin.json`, marketplace entry, README headers in both languages) 2. Create `<plugin-root>/CLAUDE.md` with a "Version Bump Locations" section listing:

• Each file path + field (e.g., `plugin.json → version`)
• Cross-package or manual-only locations flagged explicitly
• Conventional Commits → version mapping (`fix:` → patch, `feat:` → minor, `feat!:` / `BREAKING CHANGE:` → major)
• Commit scope convention (e.g., `feat(plugin-name):` for multi-plugin repos)

**Optional release automation:** If the user explicitly asks for release-please / semantic-release, see [references/plugin-templates.md](references/plugin-templates.md) for config templates. Do not prompt for it here — it i