Skip to content

mikeparcewski/wicked-garden / .claude/skills/plugin-json-schema

plugin-json-schema

Verified

Official Claude Code plugin.json schema reference and validation guide. Use when creating or troubleshooting plugin.json manifest files. Covers all fields, auto-discovery behavior, path formats, and common validation errors.

Claude Code plugin.json Schema Reference

Complete reference for Claude Code plugin manifest files.

Minimal Valid plugin.json

For plugins using standard directory structures, this is all you need:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Brief description of the plugin"
}

Auto-discovery will automatically load components from standard locations.

Complete Schema

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": "./custom/commands/",
  "agents": "./custom/agents/",
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json"
}

Field Reference

Required Fields

FieldTypeDescription
namestringUnique identifier, kebab-case, max 64 chars
versionstringSemantic version (x.y.z)
descriptionstringBrief explanation of the plugin

Optional Metadata Fields

FieldTypeDescription
authorobject{name, email?, url?}
homepagestringDocumentation URL
repositorystringSource code URL
licensestringLicense identifier (MIT, Apache-2.0, etc.)
keywordsarrayDiscovery tags (strings)

Component Path Fields

FieldTypeAuto-Discovery Location
commandsstring | arraycommands/
agentsstring | arrayagents/
skillsstring | arrayskills/
hooksstring | objecthooks/hooks.json
mcpServersstring | object.mcp.json
lspServersstring | object.lsp.json
outputStylesstring | array(none)

Auto-Discovery

Claude Code automatically loads components from standard directories without needing explicit paths in plugin.json:

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # Only manifest required here
├── commands/            # Auto-discovered: all .md files
├── agents/              # Auto-discovered: all .md files
├── skills/              # Auto-discovered: subdirs with SKILL.md
├── hooks/
│   └── hooks.json       # Auto-discovered
├── .mcp.json            # Auto-discovered
└── .lsp.json            # Auto-discovered

Key insight: If using standard directories, omit the fields entirely from plugin.json. Explicit paths are only needed for non-standard locations.

When to Use Explicit Paths

Use explicit paths only when components are in non-standard locations:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin with custom paths",
  "commands": "./src/custom-commands/",
  "agents": ["./ai/agents/reviewer.md", "./ai/agents/tester.md"],
  "hooks": "./config/hooks.json"
}

Custom paths supplement (don't replace) auto-discovered components.

Path Format Rules

Correct Path Formats

// Directory path
"commands": "./custom/commands/"

// Single file path
"hooks": "./config/hooks.json"

// Array of paths
"agents": ["./agents/agent1.md", "./agents/agent2.md"]

Invalid Path Formats (Will Cause Validation Errors)

// WRONG: Missing leading ./
"commands": "commands/"

// WRONG: Absolute path
"commands": "/Users/me/plugins/commands/"

// WRONG: Path traversal (../)
"commands": "../shared/commands/"

// WRONG: Relative to plugin.json location
"commands": "../commands"

Inline Configuration

hooks, mcpServers, and lspServers can be inline objects instead of file paths:

Inline Hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
          }
        ]
      }
    ]
  }
}

Inline MCP Servers

{
  "mcpServers": {
    "database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  }
}

Common Validation Errors

"hooks: Invalid input"

  • Cause: Using path traversal (../) or wrong type
  • Fix: Use ./hooks/hooks.json or omit field for auto-discovery

"commands: Invalid input"

  • Cause: Wrong path format or invalid type
  • Fix: Use string ("./commands/") or array (["./cmd.md"]), or omit for auto-discovery

"agents: Invalid input"

  • Cause: Wrong path format, often using object instead of string/array
  • Fix: Use string ("./agents/") or array (["./agent.md"]), or omit for auto-discovery

General Validation Failures

  1. Check all paths start with ./
  2. Remove component fields if using standard directories
  3. Verify no path traversal (../)
  4. Ensure arrays contain only strings (paths)

Best Practices

  1. Prefer minimal manifests - Only specify what's non-standard
  2. Use auto-discovery - Put components in standard directories
  3. Avoid explicit paths for standard locations - Don't add "commands": "./commands" if that's the default
  4. Use ${CLAUDE_PLUGIN_ROOT} - In hook scripts for portable paths
  5. Validate before publishing - Run claude plugin validate /path/to/plugin

Directory Structure Template

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # Minimal manifest
├── README.md             # Plugin documentation
├── commands/             # Slash commands (auto-discovered)
│   ├── deploy.md
│   └── status.md
├── agents/               # Agents (auto-discovered)
│   └── reviewer.md
├── skills/               # Skills (auto-discovered)
│   └── analysis/
│       └── SKILL.md
├── hooks/                # Hooks (auto-discovered)
│   ├── hooks.json
│   └── scripts/
│       └── post-edit.py
└── scripts/              # Shared scripts
    └── utils.py

Debugging

# Validate plugin structure
claude plugin validate /path/to/plugin

# Debug mode for detailed loading info
claude --debug

# Check what components are loaded
claude /help  # Lists available commands from plugins
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall