create-plugin-scaffold

name	create-plugin-scaffold
description	Create a new Claude Code plugin scaffold with component directories, an optional manifest, and marketplace wiring. Use when starting a new plugin or adding a plugin to a multi-plugin marketplace repository.

Create plugin scaffold

Trigger

You need to create a new Claude Code plugin from scratch and make it ready for local use or marketplace submission.

Required Inputs

• Plugin name (lowercase kebab-case)
• Plugin purpose and target users
• Component set to include (skills, agents, commands, hooks, mcpServers, workflows, output-styles)
• Repository style (single-plugin or multi-plugin marketplace)

Output Location

By default, create the plugin inside the user's local plugin directory:

~/.claude/plugins/<plugin-name>/

This path makes the plugin available for local development without publishing it. If the user explicitly asks to create the plugin elsewhere (e.g. inside an existing marketplace repo or a specific directory), respect that choice instead.

claude plugin init <plugin-name> scaffolds a starter plugin from the CLI if the user prefers the built-in generator over a hand-built tree.

Plugin layout

Everything except the manifest lives at the plugin root. Nothing but plugin.json (and, for a marketplace repo, marketplace.json) ever goes inside .claude-plugin/.

<plugin-name>/
  .claude-plugin/
    plugin.json          # manifest — OPTIONAL, only `name` is required
  skills/<skill-name>/SKILL.md
  agents/*.md
  commands/*.md
  hooks/hooks.json
  workflows/
  output-styles/
  bin/
  settings.json
  .mcp.json
  .lsp.json
  README.md
  LICENSE
  CHANGELOG.md

Discovery of these paths is automatic. You only add component keys to the manifest (skills, agents, commands, hooks, mcpServers, …) when a component lives somewhere other than its default location.

A plugin's CLAUDE.md is not loaded as context. Ship guidance through skills, agents, and hooks — never through a plugin-level CLAUDE.md.

Workflow

1. Validate the plugin name format: lowercase kebab-case, starts and ends with an alphanumeric character.
2. Determine the target directory:
   • Default: ~/.claude/plugins/<plugin-name>/
   • Override: use the path the user specifies, if any.
   • Create the directory (and parents) if it does not exist.
3. Create base files inside the target directory:
   • .claude-plugin/plugin.json (optional, but write one — it carries the display metadata)
   • README.md
   • LICENSE
   • optional CHANGELOG.md
4. Populate plugin.json:
   • Required: name — that is the only required field.
   • Recommended metadata: displayName, version, description, author, homepage, repository, license, keywords.
   • metadata is a free-form object — park anything non-spec (logo paths, internal ids) there.
   • defaultEnabled controls whether the plugin starts enabled after install.
   • Add component path keys only for non-default locations.
   • Unrecognized top-level fields are ignored at load time and reported as warnings by claude plugin validate; under --strict they fail the run. Move them into metadata instead.
5. Add userConfig if the plugin needs values from the user at enable time:
   • Each entry requires type, title, and description.
   • Optional per-entry: sensitive, required, default, multiple, min, max.
   • Reference the values as ${user_config.KEY} in MCP/LSP configs and hook commands. They are also exported to hook processes as CLAUDE_PLUGIN_OPTION_<KEY>.
   • Mark anything secret as sensitive: true; never hardcode credentials into the manifest.
6. Create component files with valid frontmatter:

Quality gates

Check these before handing the plugin back:

1. If .claude-plugin/plugin.json exists, it parses as valid JSON and has a valid kebab-case name.
2. Components live at the plugin root, not inside .claude-plugin/.
3. Manifest component keys are present only for non-default paths, and every declared path exists.
4. All paths are relative and stay inside the plugin directory — no absolute paths, no .. traversal. Use ${CLAUDE_PLUGIN_ROOT} for runtime references.
5. No unrecognized top-level manifest fields; anything extra sits under metadata.
6. Every skill directory name and every skill frontmatter name is kebab-case, so the generated /<plugin>:<skill> command is valid.
7. Agents declare only supported frontmatter — no hooks, mcpServers, permissionMode, or readonly.
8. Plugin scope stays focused on one use case, and README.md documents purpose, installation, and components.
9. claude plugin validate <plugin-dir> --strict passes.
10. New plugins are saved to ~/.claude/plugins/<plugin-name>/ by default. Only use a different location when the user explicitly requests it.

Guardrails

• Keep the plugin focused on one use case.
• Prefer concise, actionable skill text over long prose.
• Do not reference files that do not exist.
• Use folder discovery defaults unless custom paths are genuinely required.
• Do not add a plugin-level CLAUDE.md and expect it to load — it will not.
• Always save to ~/.claude/plugins/<plugin-name>/ unless the user provides a different path.

Output

• Created file tree for the plugin (with full path to the output directory)
• Final plugin.json
• Marketplace entry (if applicable)
• Short validation report of manifest fields and component metadata, including the result of claude plugin validate --strict
• Confirmation that the plugin is saved under ~/.claude/plugins/ and the install command to load it