1. Discovery — understand what the user wants to build
2. Component Planning — determine which component types are needed
3. Design & Clarifying Questions — specify each component in detail
4. Implementation — create all plugin files
5. Review & Package — deliver the

   .plugin

   file

Nontechnical output: Keep all user-facing conversation in plain language. Do not expose implementation details like file paths, directory structures, or schema fields unless the user asks. Frame everything in terms of what the plugin will do.

plugin-name/
├── .claude-plugin/
│   └── plugin.json           # Required: plugin manifest
├── commands/                 # Slash commands (.md files)
├── agents/                   # Subagent definitions (.md files)
├── skills/                   # Skills (subdirectories with SKILL.md)
│   └── skill-name/
│       ├── SKILL.md
│       └── references/
├── .mcp.json                 # MCP server definitions
└── README.md                 # Plugin documentation

• .claude-plugin/plugin.json

  is always required
• Component directories (

  commands/

  ,

  agents/

  ,

  skills/

  ) go at the plugin root, not inside

  .claude-plugin/

• Only create directories for components the plugin actually uses
• Use kebab-case for all directory and file names

Do not use or ask about this pattern by default. Only introduce

~~

placeholders if the user explicitly says they want people outside their organization to use the plugin. You can mention this is an option if it seems like the user wants to distribute the plugin externally, but do not proactively ask about this with AskUserQuestion.

create an issue in ~~project tracker

CONNECTORS.md

undefined

• What should this plugin do? What problem does it solve?
• Who will use it and in what context?
• Does it integrate with any external tools or services?
• Is there a similar plugin or workflow to reference?

• Skills — Does it need specialized knowledge that Claude should load on-demand? (domain expertise, reference schemas, workflow guides)
• Commands — Are there user-initiated actions? (deploy, configure, analyze, review)
• MCP Servers — Does it need external service integration? (databases, APIs, SaaS tools)
• Agents (uncommon) — Are there autonomous multi-step tasks? (validation, generation, analysis)
• Hooks (rare) — Should something happen automatically on certain events? (enforce policies, load context, validate operations)

| Component | Count | Purpose |
|-----------|-------|---------|
| Skills    | 1     | Domain knowledge for X |
| Commands  | 2     | /do-thing, /check-thing |
| Agents    | 0     | Not needed |
| Hooks     | 1     | Validate writes |
| MCP       | 1     | Connect to service Y |

• What user queries should trigger this skill?
• What knowledge domains does it cover?
• Should it include reference files for detailed content?

• What arguments does each command accept?
• What tools does each command need? (Read, Write, Bash, Grep, etc.)
• Is each command interactive or automated?

• Should each agent trigger proactively or only when requested?
• What tools does it need?
• What should the output format be?

• Which events? (PreToolUse, PostToolUse, Stop, SessionStart, etc.)
• What behavior — validate, block, modify, add context?
• Prompt-based (LLM-driven) or command-based (deterministic script)?

• What server type? (stdio for local, SSE for hosted with OAuth, HTTP for REST APIs)
• What authentication method?
• What tools should be exposed?

1. Create the plugin directory structure
2. Create

   plugin.json

   manifest
3. Create each component (see

   references/component-schemas.md

   for exact formats)
4. Create

   README.md

   documenting the plugin

• Commands are instructions FOR Claude, not messages to the user. Write them as directives about what to do.
• Skills use progressive disclosure: lean SKILL.md body (under 3,000 words), detailed content in

  references/

  . Frontmatter description must be third-person with specific trigger phrases.
• Agents need a description with

  <example>

  blocks showing triggering conditions, plus a system prompt in the markdown body.
• Hooks config goes in

  hooks/hooks.json

  . Use

  ${CLAUDE_PLUGIN_ROOT}

  for script paths. Prefer prompt-based hooks for complex logic.
• MCP configs go in

  .mcp.json

  at plugin root. Use

  ${CLAUDE_PLUGIN_ROOT}

  for local server paths. Document required env vars in README.

1. Summarize what was created — list each component and its purpose
2. Ask if the user wants any adjustments
3. Run

   claude plugin validate <path-to-plugin-json>

   ; fix any errors and warnings
4. Package as a

   .plugin

   file:

cd /path/to/plugin-dir && zip -r /tmp/plugin-name.plugin . -x "*.DS_Store" && cp /tmp/plugin-name.plugin /path/to/outputs/plugin-name.plugin

Important: Always create the zip in

/tmp/

first, then copy to the outputs folder. Writing directly to the outputs folder may fail due to permissions.

Naming: Use the plugin name from

plugin.json

for the

.plugin

file (e.g., if name is

code-reviewer

, output

code-reviewer.plugin

).

.plugin

• Start small: Begin with the minimum viable set of components. A plugin with one well-crafted skill is more useful than one with five half-baked components.
• Progressive disclosure for skills: Core knowledge in SKILL.md, detailed reference material in

  references/

  , working examples in

  examples/

  .
• Clear trigger phrases: Skill descriptions should include specific phrases users would say. Agent descriptions should include

  <example>

  blocks.
• Commands are for Claude: Write command content as instructions for Claude to follow, not documentation for the user to read.
• Imperative writing style: Use verb-first instructions in skills ("Parse the config file," not "You should parse the config file").
• Portability: Always use

  ${CLAUDE_PLUGIN_ROOT}

  for intra-plugin paths, never hardcoded paths.
• Security: Use environment variables for credentials, HTTPS for remote servers, least-privilege tool access.

• references/component-schemas.md

  — Detailed format specifications for every component type (commands, skills, agents, hooks, MCP, CONNECTORS.md)

• references/example-plugins.md

  — Three complete example plugin structures at different complexity levels