Plugin Dev

Plugin Development

Develop and distribute Claude Code plugins and marketplaces.

Quick Commands

# Validate marketplace/plugin
claude plugin validate .

# Test local install
/plugin marketplace add ./path/to/marketplace
/plugin install my-plugin@marketplace-name

# Check installed plugins
/plugin list

Marketplace Schema

Required fields in .claude-plugin/marketplace.json:

{
  "name": "marketplace-name",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugins/plugin-name",
      "description": "What it does"
    }
  ]
}

Plugin Schema

Required fields in .claude-plugin/plugin.json:

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

Common Errors

References

• marketplace-schema.md - Full marketplace fields
• plugin-schema.md - Full plugin fields
• validation-guide.md - Debugging validation errors
• distribution.md - Publishing to GitHub

Distribution Guide

Publishing and sharing your marketplace.

GitHub (Recommended)

1. Push to GitHub repository 2. Users add with: /plugin marketplace add owner/repo

Benefits: version control, issues, collaboration

Other Git Hosts

GitLab, Bitbucket, self-hosted:

/plugin marketplace add https://gitlab.com/team/plugins.git

Local Testing

Before publishing:

# Validate
claude plugin validate .

# Test local install
/plugin marketplace add ./my-marketplace
/plugin install my-plugin@my-marketplace

# Verify it works
/my-command

Team Configuration

Add to project's .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "team-plugins": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "my-plugin@team-plugins": true
  }
}

Team members get prompted to install when trusting the project.

Version Updates

1. Update version in marketplace.json and plugin.json 2. Push to repository 3. Users update with: /plugin marketplace update

File Caching

Plugins are copied to cache on install. This means:

• Files outside plugin dir won't be copied
• Use symlinks for shared files
• Reference files with ${CLAUDE_PLUGIN_ROOT}

Checklist

• [ ] claude plugin validate . passes
• [ ] All plugins have .claude-plugin/plugin.json
• [ ] Tested local install works
• [ ] Commands/skills function correctly
• [ ] Version numbers updated
• [ ] Pushed to repository

Marketplace Schema

Full schema for .claude-plugin/marketplace.json.

Required Fields

Owner Fields

Optional Metadata

Plugin Entries

Required

Optional

Source Formats

Relative Path

{ "source": "./plugins/my-plugin" }

GitHub

{
  "source": {
    "source": "github",
    "repo": "owner/repo"
  }
}

Git URL

{
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

Example

{
  "name": "my-marketplace",
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "metadata": {
    "description": "My awesome plugins",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./plugins/my-plugin",
      "description": "Does something useful",
      "version": "1.0.0",
      "author": { "name": "Your Name" },
      "category": "productivity",
      "keywords": ["utility", "workflow"]
    }
  ]
}

Reserved Names

Cannot use: claude-code-marketplace, claude-code-plugins, claude-plugins-official, anthropic-marketplace, anthropic-plugins, agent-skills, life-sciences

Plugin Schema

Full schema for .claude-plugin/plugin.json.

Required Fields

Optional Fields

Component Configuration

Skills Field

If specified, must be an array of paths (not names):

{
  "skills": ["./skills/my-skill", "./skills/other-skill"]
}

Recommended: Omit this field and rely on auto-discovery instead.

Directory Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # Plugin manifest
├── commands/            # Slash commands (.md files)
├── agents/              # Sub-agents (.md files)
├── skills/              # Skills (SKILL.md in subdirs)
├── hooks/               # Hook definitions
└── scripts/             # Executable scripts

Example

Minimal plugin.json (recommended):

{
  "name": "code-review",
  "description": "Adds code review commands and agents",
  "version": "1.0.0"
}

With optional metadata:

{
  "name": "code-review",
  "description": "Adds code review commands and agents",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  },
  "keywords": ["review", "code-quality"]
}

Auto-Discovery

Claude Code automatically discovers:

• commands/*.md → Slash commands
• agents/*.md → Sub-agents
• skills/*/SKILL.md → Skills
• hooks/hooks.json → Hooks

Override with explicit paths in plugin.json if needed.

Not Supported

These fields are not currently implemented (feature requests exist):

Sources

• Plugins Reference
• Anthropic skills repo

Validation Guide

Debugging plugin and marketplace validation errors.

Run Validation

# From marketplace root
claude plugin validate .

# Or inside Claude Code
/plugin validate .

Common Errors

Missing Owner

owner: Invalid input: expected object, received undefined

Fix: Add owner object:

{
  "owner": {
    "name": "Your Name"
  }
}

Plugins as Strings

plugins.0: Invalid input: expected object, received string

Fix: Change from strings to objects:

// Wrong
"plugins": ["my-plugin", "other-plugin"]

// Correct
"plugins": [
  { "name": "my-plugin", "source": "./plugins/my-plugin" },
  { "name": "other-plugin", "source": "./plugins/other-plugin" }
]

Invalid Source Path

plugins.0.source: Invalid input

Fix: Use ./ prefix for relative paths:

// Wrong
"source": "plugins/my-plugin"

// Correct
"source": "./plugins/my-plugin"

Path Traversal

plugins.0.source: Path traversal not allowed

Fix: Don't use .. in paths. Restructure so plugin is inside marketplace.

Duplicate Plugin Names

Duplicate plugin name "x" found in marketplace

Fix: Give each plugin a unique name value.

Missing plugin.json

Plugin source must contain plugin.json

Fix: Either:

1. Create .claude-plugin/plugin.json in plugin directory 2. Set "strict": false in marketplace entry

Hook Validation Errors

Schema validation failed: ok expected boolean

Stop hook error: Schema validation failed: [{"expected": "boolean", "path": ["ok"]}]

Cause: Docs show {decision, reason} schema but internal schema is {ok: boolean, reason?: string}.

Fix: Use natural language, don't mention JSON. Add model: sonnet:

{
  "type": "prompt",
  "model": "sonnet",
  "prompt": "Evaluate if the task is complete. If more work needed, condition is NOT met."
}

Why this works: Claude Code wraps your prompt with an internal evaluation prompt that forces the correct schema. Asking for JSON in your prompt conflicts with this.

Key points:

• Don't ask for JSON output in your prompt
• Must use model: sonnet (haiku unreliable)
• Internal schema: {"ok": true} or {"ok": false, "reason": "why"}
• $ARGUMENTS already prepended - don't need to specify

See GitHub Issue #11947 for details.

Hook not discovered

Cause: hooks.json placed inside skill directory instead of plugin root.

Fix: Move hooks to plugin root:

// Wrong
my-plugin/skills/my-skill/hooks/hooks.json

// Correct
my-plugin/hooks/hooks.json

Auto-discovery expects hooks/hooks.json at plugin root level.

Hook Reliability by Type

Not all hooks work reliably. Known issues as of Jan 2026:

Recommendation: Use UserPromptSubmit for reliable plugin hooks. Avoid Stop hooks for user-facing features - they fire but output is silent.

Warnings (Non-blocking)

Debugging Steps

1. Check JSON syntax: Missing commas, unquoted strings 2. Verify paths exist: ls ./plugins/my-plugin 3. Check plugin.json exists: ls ./plugins/my-plugin/.claude-plugin/ 4. Compare to working example: Check svelte-skills-kit or official demos