agentleFS
mikeparcewskimikeparcewski/wicked-garden/.claude/skills/plugin-json-schema/SKILL.md

plugin-json-schema

Skill9 starsChanged 7 months agoMITView on GitHub

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.

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 5 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Key insight: If using standard directories, omit the fields entirely from plugin.json.

    line 102
  2. Distinctive:

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

    line 106
  3. Very specific:

    Fix: Use ./hooks/hooks.json or omit field for auto-discovery

    line 193
  4. Very specific:

    Fix: Use string ("./commands/") or array (["./cmd.md"]), or omit for auto-discovery

    line 197
  5. Very specific:

    Check all paths start with ./

    line 204
  6. Distinctive:

    Remove component fields if using standard directories

    line 205
  7. Very specific:

    Verify no path traversal (../)

    line 206
  8. Distinctive:

    Ensure arrays contain only strings (paths)

    line 207
  9. Distinctive:

    Prefer minimal manifests: - Only specify what's non-standard

    line 211
  10. Distinctive:

    Use auto-discovery: - Put components in standard directories

    line 212
  11. Very specific:

    Avoid explicit paths for standard locations: - Don't add "commands": "./commands" if that's the default

    line 213
  12. Very specific:

    Validate before publishing: - Run claude plugin validate /path/to/plugin

    line 215

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.