Plugin Builder

Build or retrofit Claude Code plugins that are loadable, portable, namespaced, testable, and ready for team or marketplace distribution. [DOC]

When to Activate

Activate for plugin authoring, plugin migration, plugin packaging, local plugin testing, marketplace readiness, or component authoring under a plugin root. [CONFIG]

Do not activate for a single personal/project skill unless the user asks to distribute it as a plugin. Use standalone .claude/ configuration for personal workflows, one-project customization, quick experiments, or short direct skill names such as /deploy. Use plugins for teammate/community sharing, versioned releases, reuse across projects, marketplace distribution, or namespaced invocation such as /my-plugin:deploy. [DOC]

Authoring Contract

Start with read-only discovery. Identify the target mode before writing:

Record coverage_gap when the active Claude Code version, marketplace policy, or external dependency behavior cannot be verified. [CONFIG]

Layout, Manifest & Components

The default scaffold layout, the manifest/metadata rules (optionality, recommended fields, ${CLAUDE_PLUGIN_ROOT} paths), the plugin-manifest-vs-marketplace-catalog distinction with examples, and per-component authoring guidance live in references/plugin-authoring-detail.md. Official structure specs are vendored in references/official-specs/ (plugin/skill/agent/hook + manifest templates; mirror of docs.claude.com). Two invariants stay here: components live at plugin root (only plugin.json inside .claude-plugin/), and a root CLAUDE.md is not loaded as plugin context. [DOC]

Install-breaker rule (the manifest gate): plugin.json must OMIT skills/agents/hooks/commands — they auto-discover (./skills, …). Declaring them (string path override) is rejected by the installer with Invalid input; repository must be a string. ${CLAUDE_PLUGIN_ROOT}/scripts/validate_manifest.py BLOCKS on these. For the publish/install flow + troubleshooting see docs/DEPLOY.md; for the operate-forever lifecycle use the plugin-ops skill. [CÓDIGO]

Procedure

1. Gather plugin name, audience, sharing intent, components, runtime dependencies, security posture, and release channel.
2. Decide standalone versus plugin. Do not package a plugin when a local .claude/ skill is enough.
3. Scaffold the smallest valid plugin layout with ${CLAUDE_PLUGIN_ROOT}/scripts/scaffold_plugin.py <dir>/<name>: it emits an installer-safe manifest, hooks that read stdin JSON, a smoke skill, portable validators, tests/hooks.sh and a one-command scripts/check.sh whose gates are proven able to go red by the emitted gate-bites unit tests. Create optional component folders only when justified. [CÓDIGO]
4. Write or update .claude-plugin/plugin.json only when metadata or custom paths are needed.
5. Author skills, agents, hooks, MCP (Model Context Protocol) servers, LSP (Language Server Protocol) servers, monitors, output styles, themes, bin helpers, and settings with namespaced operation in mind.
6. Add README.md, LICENSE, CHANGELOG.md, dependency notes, env-var setup, trust boundaries, and examples for marketplace or team distribution.
7. Use assets/plugin-readiness-checklist.md for release-readiness reviews and assets/marketplace-submission-gates.md for marketplace handoff gates. [CONFIG]
8. Validate with the toolkit gates in order: /claude-native-toolkit:check (structure + frontmatter + evals + packet), /claude-native-toolkit:lint (component bodies), /claude-native-toolkit:audit (manifest, paths, executable surface), and /claude-native-toolkit:integrity (catalog/hook consistency). If the external plugin-qa plugin is present, run its granular validate-* skills first; otherwise treat the toolkit gates above as the binding gate. See Relation To Validator Skills for the responsibility split and the probe-then-fallback rule.
9. Test locally with claude --plugin-dir ./<plugin-root> or a .zip archive when supported, then reload after component changes via the CLI /plugin reload action (built-in). Try /plugin-name:skill-name, check /agents, verify hooks, and inspect plugin details when available.
10. Run claude plugin validate ./<plugin-root> for each plugin and claude plugin validate . from the marketplace root before submission. Use --strict when the active CLI supports it. [DOC]

Marketplace Readiness & Submission Gates

The publish checklist (metadata, README/LICENSE/CHANGELOG, namespacing, side-effect disclosure, catalog entries, community-vs-official routing) and the G1–G6 submission gate table live in references/plugin-authoring-detail.md. Hard rule: community submission ≠ official inclusion — never promise an official-marketplace path. [DOC]

Relation To Validator Skills

The granular validate-* skills are external — they ship in the plugin-qa plugin, not in this toolkit. Treat them as reference gates and do not duplicate them. This section is the single source for the validator boundary; the Procedure and Marketplace Readiness gates reference it instead of restating it.

Probe-before-declare: glob the plugin cache (for example cache/*/plugin-qa/*) before claiming plugin-qa is absent or claiming you can run it. [CONFIG] In development-kit marketplaces plugin-qa is usually present (e.g. cache/development-kit/plugin-qa/<version>/skills/ exposing validate-structure/validate-manifest/validate-components/validate-cross-refs/validate-hooks), so a probe typically resolves it — do not assume absence by default. Record coverage_gap only if the probe leaves residency unresolved. Responsibility split:

• validate-structure owns mode detection, component placement, path traversal, layout, and executable surface.
• validate-manifest owns JSON parsing, required/recommended fields, name/version/license/keyword quality, and marketplace/catalog consistency once the manifest path is known.
• validate-components owns skill, command, agent, and output-style frontmatter/body checks.
• validate-hooks owns hook event shape, handler schema, matcher behavior, script portability, and hook execution risks.
• Fallback when plugin-qa is absent: map to this toolkit's own gates — /claude-native-toolkit:check + /claude-native-toolkit:audit (layout/manifest/surface), /claude-native-toolkit:lint (components), /claude-native-toolkit:integrity (hooks/catalog) — and claude plugin validate ./<plugin-root> as the version-agnostic CLI baseline.
• If validator guidance conflicts, prefer validate-structure for physical layout and record a coverage_gap for the conflicting rule before submission. [CONFIG]

Validation Gate

The full success checklist (structure, manifest, components, namespacing, portability, testing, distribution, submission) is in references/plugin-authoring-detail.md. Declare success only when every applicable check passes; the Guardian role enforces the same.

References And Assets

• references/domain-knowledge.md: detailed plugin-authoring rules and source mapping.
• knowledge/body-of-knowledge.md: compact mental model and quality metrics.
• examples/example-input.md and examples/example-output.md: non-generic plugin-authoring example.
• evals/evals.json: regression cases for plugin-authoring behavior.
• assets/plugin-readiness-checklist.md: checklist template to include in release reviews.
• assets/marketplace-submission-gates.md: submission gate template for marketplace handoff.

Contract

• Aceptación: plugin cargable, namespaced, portable (${CLAUDE_PLUGIN_ROOT}), validado y testeado local. [EXPLICIT]
• Límites: empaqueta/distribuye; no garantiza inclusión en marketplace oficial. [EXPLICIT]
• Casos borde: componentes en root (solo plugin.json en .claude-plugin/); CLAUDE.md root no se carga. [EXPLICIT]
• Supuestos: auto-discovery si se omite manifest [DOC]. [SUPUESTO]
• Trade-off: plugin vs .claude/ standalone — compartible/versionado a cambio de overhead de empaque. [EXPLICIT]

Packet

Capas del packet, cargables bajo demanda (disciplina ICM: una capa por vez, nunca todas juntas): references/ guías de profundidad (cargar UNA por etapa) · knowledge/ cuerpo de conocimiento · prompts/ prompts listos · examples/ salida de ejemplo · agents/ subagentes del packet · templates/ plantilla de output · assets/ recursos estáticos.