Skip to content
Skills Library
AI & agents · Research

plugin-json-schema

/plugin-json-schema

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.

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Original author description

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.

How it works

  1. Minimal Valid plugin.json
  2. Complete Schema
  3. Field Reference
  4. Auto-Discovery
  5. When to Use Explicit Paths
  6. Path Format Rules
  7. Inline Configuration
  8. Common Validation Errors
  9. Best Practices
  10. Directory Structure Template
Original SKILL.md headings · 245 lines, 806 words
SKILL.md preview
---
name: plugin-json-schema
description: |
  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:

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

**Auto-discovery** will automatically load components from standard locations.

## Complete Schema

```json
{
  "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

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Unique identifier, kebab-case, max 64 chars |
| `version` | string | Semantic version (x.y.z) |
| `description` | string | Brief explanation of the plugin |

### Optional Metadata Fields

| Field | Type | Description |
|-------|------|-------------|
| `author` | object | `{name, email?, url?}` |
| `homepage` | string | Documentation URL |
| `repository` | string | Source code URL |
| `license` | string | License identifier (MIT, Apache-2.0, etc.) |
| `keywords` | array | Discovery tags (strings) |

### Component Path Fields

| Field | Type | Auto-Discovery Location |
|-------|------|-------------------------|
| `commands` | string \| array | `commands/` |
| `agents` | string \| array | `agents/` |
| `skills` | string \| array | `skills/` |
| `hooks` | string \| object | `hooks/hooks.json` |
| `mcpServers` | string \| object | `.mcp.json` |
| `lspServers` | string \| object | `.lsp.json` |
| `outputStyles` | string \| 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:

```json
{
  "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

```json
// 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)

```json
// 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

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

### Inline MCP Servers

```json
{
  "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

```bash
# 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
```

Versions

The database has no other skills named plugin-json-schema.

Database snapshot: 13.11.2026 · package version 29f663848712 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100claude-plugins
    Guide for creating and validating Claude Code plugin.json files. Use when creating plugins, validating plugin schemas, or troubleshooting plugin configuration.
  • 100plugin-structure
    This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "configure auto-discovery", or needs…
  • 95plugin-structure
    This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "configure auto-discovery", or needs…
  • 100plugin-validation
    Validates the structural correctness of Claude Code plugins — plugin.json manifest fields, SKILL.md YAML frontmatter, reference cross-references, skill name-to-directory consistency, and plugin structure conventions. Use when checking whether a plugin is well-formed before…
  • 100cc-plugin-development
    Build, validate, and publish Claude Code plugins — manifest schema, skill/command/agent/hook authoring, MCP server integration, marketplace publishing, version management. Use this skill whenever creating a new plugin, adding a skill/command/agent to an existing plugin,…
  • 100plugin-authoring
    Use when creating, modifying, or debugging Claude Code plugins. Triggers on .claude-plugin/, plugin.json, marketplace.json, commands/, agents/, skills/, hooks/ directories. Provides schemas, templates, validation workflows, and troubleshooting.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.