Plugin Building and Packaging

Package your skills, agents, commands, and hooks as distributable plugins.

Plugin Structure

CRITICAL RULE: Only plugin.json goes inside .claude-plugin/ . All components go at the plugin ROOT:

my-plugin/ <- Plugin name = neutral noun ├── .claude-plugin/ │ └── plugin.json # ONLY this file here! ├── commands/ # Slash commands (.md) - imperative verbs ├── agents/ # Agent definitions (.md) - role nouns ├── skills/ # Skills (*/SKILL.md) - ending in -ing ├── hooks/ # Event handlers (hooks.json) ├── .mcp.json # MCP servers (optional) ├── .lsp.json # LSP servers (optional) └── README.md

❌ WRONG - components inside .claude-plugin/

.claude-plugin/ ├── plugin.json ├── commands/ ← NO! └── skills/ ← NO!

✅ CORRECT - components at plugin root

.claude-plugin/ └── plugin.json commands/ ← YES! skills/ ← YES!

plugin.json Manifest

Required fields:

{ "name": "my-plugin", "version": "1.0.0", "description": "What this plugin does" }

With recommended metadata:

{ "name": "my-plugin", "version": "1.0.0", "description": "What this plugin does", "author": { "name": "Your Name", "email": "you@example.com" }, "license": "MIT", "keywords": ["keyword1", "keyword2"], "repository": "https://github.com/user/repo", "homepage": "https://github.com/user/repo#readme" }

See references/plugin-json-schema.md for the complete field reference.

Naming Conventions

See /metaskill-naming for the full naming convention.

Quick reference:

Component Form Example

Plugin name Neutral noun metaskill, codeforge, datakit

Skills -ing (gerund) metaskill-authoring, metaskill-triggering

Agents Role noun metaskill-trigger-tester, metaskill-analyzer

Commands Imperative verb /metaskill-create, /quick-start

Plugin name = Common prefix of all atoms

✅ GOOD - neutral noun prefix, correct suffixes

metaskill/ ├── skills/ │ ├── metaskill-authoring/ # -ing │ └── metaskill-triggering/ # -ing ├── agents/ │ └── metaskill-trigger-tester.md # role noun └── commands/ └── quick-start.md # imperative

❌ BAD - verb-form prefix

skill-authoring/ ├── skills/ │ └── skill-authoring-trigger/ # prefix already -ing!

No type postfixes:

❌ BAD - redundant type postfix

skills/code-review-skill/ agents/tester-agent.md commands/lint-command.md

✅ GOOD - no type postfix

skills/code-reviewing/ agents/tester.md commands/lint.md

Dogfooding Approaches

Quick Iteration (Active Development)

claude --plugin-dir ./my-plugin

• Loads plugin immediately

• Restart Claude Code to pick up changes

• Best for rapid iteration

Marketplace Testing (Pre-Release)

Add your repo as a local marketplace (once)

/plugin marketplace add /path/to/your/repo

Install the plugin

/plugin install your-repo@my-plugin

After changes, reinstall to test

/plugin uninstall your-repo@my-plugin /plugin install your-repo@my-plugin

• Tests the full installation flow

• Verifies the user experience

• Use before releasing

Plugin Placement in Repos

Single Plugin at Repo Root

For a repo that IS the plugin:

my-plugin-repo/ ├── .claude-plugin/ │ └── plugin.json ├── skills/ │ └── my-plugin-authoring/ ├── agents/ └── README.md

Plugin Inside a Project (Dogfooding)

For internal tooling within a larger project:

my-project/ ├── src/ ├── tests/ ├── .claude/ # Project's Claude config │ └── settings.json └── plugins/ └── my-internal-plugin/ ├── .claude-plugin/ │ └── plugin.json └── skills/

Load with: claude --plugin-dir ./plugins/my-internal-plugin

Multiple Plugins in One Repo

Use marketplace.json to reference multiple plugins:

my-repo/ ├── .claude-plugin/ │ └── marketplace.json # References plugins below ├── plugins/ │ ├── plugin-a/ │ │ ├── .claude-plugin/ │ │ │ └── plugin.json │ │ └── skills/ │ └── plugin-b/ │ ├── .claude-plugin/ │ │ └── plugin.json │ └── agents/ └── README.md

marketplace.json (required fields):

{ "name": "my-marketplace", "owner": { "name": "Your Name" }, "plugins": [ { "name": "plugin-a", "source": "./plugins/plugin-a" }, { "name": "plugin-b", "source": "./plugins/plugin-b" } ] }

With full metadata:

{ "name": "my-marketplace", "owner": { "name": "Your Name", "email": "you@example.com" }, "metadata": { "description": "Description of your marketplace", "version": "1.0.0" }, "plugins": [ { "name": "plugin-a", "source": "./plugins/plugin-a", "description": "What plugin-a does", "version": "1.0.0", "author": { "name": "Your Name", "email": "you@example.com" }, "license": "MIT", "keywords": ["keyword1", "keyword2"], "category": "development" } ] }

See references/marketplace-json-schema.md for the complete field reference.

Users can then:

/plugin marketplace add /path/to/my-repo /plugin install my-marketplace@plugin-a

Internal vs External Plugins

Internal (Dogfooding within Repo)

Place in a plugins/ or tools/ directory:

my-project/ ├── plugins/ │ └── internal-tooling/ # For this project only │ ├── .claude-plugin/ │ │ └── plugin.json │ └── skills/

• Not meant for distribution

• Project-specific utilities

• Load with --plugin-dir

External (Open Source / Distribution)

Option A: Dedicated plugin repo

my-plugin/ # Repo IS the plugin ├── .claude-plugin/ │ └── plugin.json └── skills/

Option B: Plugin marketplace repo

my-plugins/ # Repo contains multiple plugins ├── .claude-plugin/ │ └── marketplace.json └── plugins/ ├── plugin-a/ └── plugin-b/

Plugin Components Reference

Directory Contents Naming Pattern

.claude-plugin/

plugin.json only N/A

skills/

*/SKILL.md

prefix-action-ing

agents/

*.md

prefix-role-noun

commands/

*.md

imperative-verb

hooks/

hooks.json

N/A

.mcp.json

MCP servers N/A

.lsp.json

LSP servers N/A

Common Mistakes

Components in Wrong Location

❌ WRONG

.claude-plugin/ ├── plugin.json └── skills/ # NO! Skills outside .claude-plugin/

✅ CORRECT

.claude-plugin/ └── plugin.json skills/ # YES! At plugin root

Missing plugin.json

❌ WRONG - no manifest

my-plugin/ └── skills/

✅ CORRECT - has manifest

my-plugin/ ├── .claude-plugin/ │ └── plugin.json └── skills/

Verb-Form Prefix

❌ WRONG - prefix is already -ing

skill-authoring/ ├── skills/ │ └── skill-authoring-triggering/ # Double verb!

✅ CORRECT - neutral noun prefix

metaskill/ ├── skills/ │ └── metaskill-triggering/ # Noun + -ing

Related Skills

• For naming conventions, see /metaskill-naming

• For skill structure and writing, see /metaskill-authoring

• For skill group patterns, see /metaskill-grouping

• For trigger optimization, see /metaskill-triggering

• To test if triggers work, use the metaskill-trigger-tester agent