plugin-json-schema

分类: 文档与知识管理 | 上传者: mikeparcewski | 下载: 0 | 版本: v1.0（最新）

官方克劳德代码plugin.json架构参考和验证指南。在创建plugin.json 清单文件或对其进行故障排除时使用。涵盖所有字段、自动发现行为、路径格式和常见验证错误。 --- # Claude Code plugin.json 架构参考 Claude Code 插件清单文件的完整参考。 ## 最小有效的plugin.json 对于使用标准目录结构的插件，这就是您所需要的： ```json { "name": "my-plugin", "version": "1.0.0", "description": "Brief description of the plugin" } ``` **自动发现** 将自动从标准位置加载组件。 ## 完整架构 ```json { "name": "plugin-name", "version": "1.2.0", "description": "简要插件描述", "author": { "name": "作者姓名", "email": "[email protected]", "url": "https://github.com/author" }, "homepage": "https://docs.example.com/plugin", "repository": “https://github.com/author/plugin”，“许可证”：“MIT”，“关键字”：[“关键字1”，“关键字2”]，“命令”：“./custom/commands/”，“代理”：“./custom/agents/”，“技能”：“./custom/skills/”，“钩子”：“./config/hooks.json”，“mcpServers”： "./mcp-config.json", "outputStyles": "./styles/", "lspServers": "./.lsp.json" } ``` ## 字段参考 ### 必填字段 |领域|类型 |描述 | |--------|------|-------------| | `名称` |字符串|唯一标识符，短横线大小写，最多 64 个字符 | | `版本` |字符串|语义版本 (x.y.z) | | `描述` |字符串|插件简单说明| ### 可选元数据字段 ds |领域|类型 |描述 | |--------|------|-------------| | `作者` |对象| `{姓名、电子邮件？、网址？}` | | `主页` |字符串|文档网址 | | `存储库` |字符串|源代码网址| | `许可证` |字符串|许可证标识符（MIT、Apache-2.0 等）| | `关键字` |数组|发现标签（字符串）| ### 组件路径字段 |领域|类型 |自动发现位置 | |--------|------|-------------------------| | `命令` |字符串\|数组| `命令/` | | `代理人

更新日志: Source: GitHub https://github.com/mikeparcewski/wicked-garden

目录结构

当前层级: tree/main/.claude/skills/plugin-json-schema/

📄 SKILL.md 6.7 KB

SKILL.md

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

登录后下载/点赞/收藏 ❤ 8 | ★ 0

plugin-json-schema

目录结构

SKILL.md

举报内容

提示