Plugin Creation

Plugin Creation

Create complete Claude Code plugins with any combination of components.

When to Use

• "Create a plugin" / "Make a new plugin"
• "Add a skill" / "Create command" / "Make agent"
• "Add hooks" / "Setup MCP server"
• "Configure settings" / "Setup output directory"
• "Package for marketplace"
• NOT for: Using existing plugins (see /plugin command)

Quick Reference

| Component | Location | Invocation | Best For | |-----------|----------|------------|----------| | Skills | skills/name/SKILL.md | Model-invoked (auto) | Complex workflows with resources | | Commands | commands/name.md | User (/command) | Quick, frequently used prompts | | Agents | agents/name.md | Auto + Manual | Task-specific expertise | | Hooks | hooks/hooks.json | Event-triggered | Automation and validation | | MCP | .mcp.json | Auto startup | External tool integration |

Before Creating

1. Read references/01-overview/component-comparison.md to decide which components needed
2. Determine if this should be a new plugin or add to existing

Plugin Project Setup

When creating any plugin, also consider:

• .claude/rules/ with modular project rules (path-scoped if needed for different component directories)
• Maintainer/contributor conventions belong in a CONTRIBUTING.md at the plugin root — not a CLAUDE.md. A plugin-root CLAUDE.md is NOT loaded as project context when the plugin is installed; both claude plugin validate and this validator (rule ST03, warn) flag one. To ship instructions Claude reads at runtime, put them in a skill (skills//SKILL.md); for path-scoped editing rules use .claude/rules/.
• README.md and CHANGELOG.md at plugin root (for humans — never inside skill directories)

Documentation Principles

All plugin documentation should follow lean principles:

• Current truth only — no historical narratives or "previously we did X"
• Replace, don't append — superseded content gets replaced entirely
• Delete what's irrelevant — every edit is a chance to prune
• Read references/02-philosophy/core-philosophy.md for full philosophy

Plugin Initialization

When user says "create plugin", "initialize plugin", "new plugin":

Option A - Use init script:

python scripts/init_plugin.py my-plugin --path ./plugins --components skill,command,hook

Option B - Manual creation:

1. Create plugin directory structure:

`` plugin-name/ ├── .claude-plugin/ │ └── plugin.json ├── commands/ # if needed ├── agents/ # if needed (recursively scanned — subfolders join the scoped id, e.g. agents/review/security.md → my-plugin:review:security) ├── skills/ # if needed │ └── skill-name/ │ └── SKILL.md ├── hooks/ # if needed │ └── hooks.json └── .mcp.json # if needed ``

Single-skill minimum layout (v2.1.142+): if the plugin is exactly one skill and nothing else, put SKILL.md at the plugin root with no skills/ subdirectory and no skills field — Claude Code auto-discovers it. See references/08-configuration/plugin-json.md § Important Path Rules item 4.

1. Copy template from templates/plugin.json.template

1. Ask user which components they need

Creating Skills

When user says "add skill", "create skill", "make skill":

1. Read references/03-skills/writing-skillmd.md for structure
2. Copy template from templates/skill/SKILL.md.template
3. Key requirements:

• Name: lowercase, hyphens, max 64 chars
• Description: WHAT it does + WHEN to use it, max 1024 chars, third person
• Body: imperative instructions, under 500 lines
• Use progressive disclosure - reference files for details

Critical: SKILL.md files are INSTRUCTIONS for Claude, not documentation. Write imperatives telling Claude what to do.

| Documentation (WRONG) | Instructions (CORRECT) | |----------------------|------------------------| | "This skill helps with PDF processing" | "Process PDF files using this workflow" | | "The description field is important" | "Write the description starting with 'Use when...'" |

Consider these optional frontmatter fields:

• model: — opus (safe, 1M) or inherit (safe default). Do NOT pin sonnet/haiku on a skill — a skill's model: is an inline current-turn override with no context isolation, so a sub-1M pin overflows when the skill activates from a large conversation (validator rule S14). For cheap heavy work, put it in a Task-dispatched agent instead. See references/03-skills/writing-skillmd.md § Don't pin a skill below the session window.
• context: fork with agent: for heavy operations that would pollute main context
• disallowed-tools (kebab-case) to hard-remove tools from the pool while the skill runs (e.g. block AskUserQuestion in a background loop). Note the agent equivalent is camelCase disallowedTools — the forms are not interchangeable (rules S15 / A04).
• disable-model-invocation: true for command-only skills (no auto-trigger)
• user-invocable: false to hide from / menu (Claude can still invoke via Skill tool)

Dynamic context injection: Use ` !command ` in the skill body to inject runtime state (git status, file contents, etc.) when the skill loads.

Extended thinking: Include "ultrathink" in the skill body for tasks requiring deep reasoning.

Creating Commands

When user says "add command", "create command", "slash command":

1. Read references/04-commands/writing-commands.md
2. Copy template from templates/command/command.md.template
3. Key requirements:

• Frontmatter: description, allowed-tools, argument-hint
• Support $ARGUMENTS, $1, $2 for arguments
• Prefix lines with exclamation mark for bash execution
• Prefix lines with at-sign for file references

Creating Agents

When user says "add agent", "create agent", "make agent":

1. Read references/05-agents/writing-agents.md
2. Copy template from templates/agent/agent.md.template
3. Key requirements:

• Frontmatter: name, description, tools, model, permissionMode
• Description should include "Use proactively" for auto-delegation
• One agent = one clear responsibility

Consider these agent-specific features:

• memory: project for agents that benefit from cross-session learning (architecture decisions, code review patterns)
• memory: user for personal preferences that carry across projects
• model: matched to task complexity — haiku for lookup/formatting, sonnet for balanced tasks, opus for complex reasoning
• tools restriction to minimum needed (reduces cost and attack surface)
• disallowedTools to block specific tools (e.g., Edit, Write for read-only agents)
• hooks in agent frontmatter for scoped validation (runs only when that agent is active)

Agent teams: For tasks benefiting from multiple perspectives or parallel research, consider agent teams (competing perspectives, hypothesis investigation, parallel tasks). See references/05-agents/agent-patterns.md for team patterns. Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

Creating Hooks

When user says "add hooks", "setup hooks", "event handlers":

1. Read references/06-hooks/writing-hooks.md
2. Read references/06-hooks/hook-events.md for all 30 events
3. Copy template from templates/hooks/hooks.json.template
4. Key events:

• Setup - one-time --init-only / --init -p / --maintenance -p preparation. Distinct from SessionStart: Setup does NOT fire on every launch, so a plugin that needs a dependency installed cannot rely on Setup alone — pair with a ${CLAUDE_PLUGIN_DATA} "check on first use, install on miss" pattern.
• PreToolUse - before tool execution (can block)
• PostToolUse - after tool execution (formatting, logging). Use the updatedToolOutput JSON return field to rewrite what Claude sees (replaces the older MCP-only updatedMCPToolOutput).
• PostToolBatch - after a parallel batch resolves (one-shot summary)
• SessionStart - setup, output directories
• SessionEnd - cleanup
• UserPromptSubmit - validation, context injection (can block)
• UserPromptExpansion - intercept direct /skillname invocations (can block)
• SubagentStart/SubagentStop - agent lifecycle
• WorktreeCreate/WorktreeRemove - replace default git worktree behavior with custom VCS logic (SVN/Perforce/Mercurial). Input: name via stdin; WorktreeCreate must print the worktree path on stdout, and any non-zero exit aborts creation.
• PreCompact - inject context before compaction
• Notification, Stop, TaskCompleted, TeammateIdle

Adaptive hooks: Hook stdin JSON includes an effort object ({ "level": ... }) on tool-use-context events; the same level is exported as $CLAUDE_EFFORT to command hooks and the Bash tool. Use it to adapt verbosity, recursion depth, or external-call budget to the user's effort setting.

Exec form vs shell form (v2.1.139+): Command hooks run in exec form when args is set — command resolves as an executable and is spawned directly with each args element passed as one argument, no shell tokenization, no quoting. Prefer exec form for any hook that references a path placeholder (${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_DATA}). Omit args to fall back to shell form when you need pipes, &&, or redirects.

No controlling terminal (v2.1.139+): On macOS and Linux, command hooks run without /dev/tty. To surface a message, return systemMessage in JSON stdout; to ring the bell or fire a desktop notification, return terminalSequence (allowlisted OSC sequences). All hook output is capped at 10,000 characters — longer output is replaced with a file-path preview.

Five handler types — choose the right one:

• command — shell script, fastest, no LLM cost. Use for logging, file ops, env setup.
• http — POST event JSON to a webhook (settings.json only). Use for external services.
• mcp_tool — call a tool on an already-connected MCP server, no shell. Use to file an issue, sync state, log to an external system without spawning a process.
• prompt — single-turn LLM evaluation, zero script overhead. Use for lightweight validation.
• agent — multi-turn subagent with tools (Read, Grep, Glob). Experimental upstream — behavior may change.

Async execution: Add "async": true on command hooks for background operations (logging, analytics) that shouldn't block the main flow.

MCP tool matching: Use mcp____ pattern in matchers for PreToolUse/PostToolUse.

Session-remembrance pattern: For plugins that maintain per-project state, /plugin-creation-tools:add-component remembrance-hooks scaffolds a SessionStart + SessionEnd hook pair (plus the install command, /save-session command, and save-session.sh) that survives compaction / /clear / new sessions. Two design rules are non-negotiable: no PostCompact hook (its stdout isn't injected into context — a no-matcher SessionStart covers compaction), and copy save-session.sh into the project (${CLAUDE_PLUGIN_ROOT} doesn't resolve in a project settings.json). See references/06-hooks/remembrance-hooks-pattern.md.

Configuring Plugin

When user says "configure plugin", "setup plugin.json":

1. Read references/08-configuration/plugin-json.md for full schema
2. Required fields: name
3. Recommended fields: $schema (SchemaStore JSON Schema for editor autocomplete), version, description, author, license
4. Component paths: commands (array), agents (array — string form no longer accepted), hooks, mcpServers
5. Experimental components (themes, monitors) belong under experimental.*. Top-level themes / monitors still load but claude plugin validate warns and a future release will require the nested form. The validator (/plugin-creation-tools:validate) flags top-level usage and offers an auto-migration diff.
6. Niche but valid manifest fields: channels (Telegram/Slack/Discord-style message injection — each entry binds to one of the plugin's mcpServers); bin/ directory auto-discovered (executables there are added to the Bash tool's PATH while the plugin is enabled — chmod +x; useful for CLI helpers users invoke directly, distinct from hooks/ which are event-driven). Plugin-root settings.json supports two keys: agent (activates one of the plugin's agents as the main thread agent) and subagentStatusLine (default status-line config for subagents). See references/08-configuration/plugin-json.md and references/08-configuration/settings.md.

Suppressing a plugin skill without forking

Users who want to silence a single plugin skill don't need to uninstall the plugin or edit its SKILL.md. Two escape hatches, in priority order:

• skillOverrides setting (.claude/settings.local.json) — four states: on / name-only / user-invocable-only / off. The /skills menu writes this for them. Note: upstream caveat is that skillOverrides does NOT affect plugin-shipped skills — for those, point users at /plugin disable for the whole plugin. Surface this in your README's troubleshooting section.
• /plugin disable @ for the entire plugin, scoped per scope (user/project/local).

See references/08-configuration/settings.md#skilloverrides for details.

Settings and Output

When user says "configure settings", "setup output", "output directory":

1. Read references/08-configuration/settings.md for settings hierarchy
2. Read references/08-configuration/output-config.md for output patterns
3. Key environment variables:

• ${CLAUDE_PLUGIN_ROOT} - plugin installation directory
• ${CLAUDE_PROJECT_DIR} - project root
• ${CLAUDE_ENV_FILE} - persistent env vars (SessionStart only)

1. Use SessionStart hook to create output directories

Testing Plugin

When user says "test plugin", "validate plugin":

1. Read references/09-testing/testing.md
2. Run claude --debug to see plugin loading
3. Validate plugin.json syntax
4. Test each component:

• Skills: Ask questions matching description
• Commands: Run /command-name
• Agents: Check /agents listing
• Hooks: Trigger events manually

Packaging for Marketplace

When user says "package plugin", "publish plugin", "marketplace":

1. Read references/10-distribution/packaging.md
2. Create marketplace.json in repository root
3. Update README with installation instructions
4. Version using semantic versioning (MAJOR.MINOR.PATCH)

Decision Framework

Before creating a component, verify it's the right choice:

| Component | Use When | |-----------|----------| | Skill | Complex workflow, needs resources, auto-triggered by context | | Command | User should trigger explicitly, quick one-off prompts | | Agent | Specialized expertise, own context window, proactive delegation | | Hook | Event-based automation, validation, logging | | MCP | External API/service, custom tools, database access |

The 5-10 Rule: Done 5+ times? Will do 10+ more? Create a skill or command.

References

Overview

• references/01-overview/what-are-plugins.md - Plugin overview
• references/01-overview/what-are-skills.md - Skills overview
• references/01-overview/what-are-commands.md - Commands overview
• references/01-overview/what-are-agents.md - Agents overview
• references/01-overview/what-are-hooks.md - Hooks overview
• references/01-overview/what-are-mcp.md - MCP overview
• references/01-overview/component-comparison.md - When to use what

Philosophy

• references/02-philosophy/core-philosophy.md - Design principles
• references/02-philosophy/decision-frameworks.md - Decision trees
• references/02-philosophy/anti-patterns.md - What to avoid

Components

• references/03-skills/anthropic-skill-standards.md - Official Anthropic skill standards and checklist
• references/03-skills/skill-patterns.md - Five skill patterns (Seq

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: camoa
• Source: camoa/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.