claude-plugins

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code Plugin

Claude Code 插件

Guide for creating, validating, and managing plugin.json files for Claude Code plugins. Includes schema validation, best practices, and automated tools.

本文为Claude Code插件的plugin.json文件创建、验证与管理指南，包含Schema验证、最佳实践及自动化工具说明。

When to Use This Skill

何时使用本技能

Activate this skill when:

Creating or editing
```
.claude-plugin/plugin.json
```
files
Validating plugin.json schema compliance
Setting up new plugin directories
Troubleshooting plugin configuration issues
Understanding plugin manifest structure

在以下场景激活本技能：

创建或编辑
```
.claude-plugin/plugin.json
```
文件
验证plugin.json的Schema合规性
搭建新插件目录结构
排查插件配置问题
理解插件清单结构

Plugin Manifest Schema

插件清单 Schema

File Location

文件位置

All plugin manifests must be located at

.claude-plugin/plugin.json

within the plugin directory.

所有插件清单必须位于插件目录下的

.claude-plugin/plugin.json

路径。

Complete Schema

完整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/special.md"],
  "agents": "./custom/agents/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "skills": ["./skills/skill-one", "./skills/skill-two"]
}

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/special.md"],
  "agents": "./custom/agents/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "skills": ["./skills/skill-one", "./skills/skill-two"]
}

Required Fields

必填字段

```
name
```
: Plugin identifier (kebab-case, lowercase alphanumeric and hyphens only)

```
name
```
：插件标识符（仅允许kebab-case格式，即小写字母、数字及连字符）

Optional Fields

可选字段

Metadata:

```
version
```
: Semantic version number (recommended)
```
description
```
: Brief explanation of plugin functionality
```
license
```
: SPDX license identifier (e.g., MIT, Apache-2.0)
```
keywords
```
: Array of searchability and categorization tags
```
homepage
```
: Documentation or project URL
```
repository
```
: Source control URL

Author Information:

```
author.name
```
: Creator name
```
author.email
```
: Contact email
```
author.url
```
: Personal or organization website

Component Paths:

```
skills
```
: Array of skill directory paths (relative to plugin root)
```
commands
```
: String path or array of command file/directory paths
```
agents
```
: String path or array of agent file paths
```
hooks
```
: String path to hooks.json or hooks configuration object
```
mcpServers
```
: String path to MCP config or configuration object

元数据：

```
version
```
：语义化版本号（推荐使用）
```
description
```
：插件功能简要说明
```
license
```
：SPDX许可证标识符（如 MIT、Apache-2.0）
```
keywords
```
：用于插件发现、搜索与分类的字符串数组
```
homepage
```
：文档或项目官网URL
```
repository
```
：源代码仓库URL

作者信息：

```
author.name
```
：创作者姓名
```
author.email
```
：联系邮箱
```
author.url
```
：个人或组织官网

组件路径：

```
skills
```
：技能目录路径数组（相对于插件根目录）
```
commands
```
：单个命令文件/目录路径或路径数组
```
agents
```
：单个Agent文件目录或文件路径数组
```
hooks
```
：hooks.json文件路径或hooks配置对象
```
mcpServers
```
：MCP配置文件路径或配置对象

Field Validation Rules

字段验证规则

name

Format: kebab-case (lowercase alphanumeric and hyphens only)
Pattern:
```
^[a-z0-9]+(-[a-z0-9]+)*$
```

Examples:

Valid:
```
my-plugin
```
,
```
core-skills
```
,
```
elixir-tools
```
Invalid:
```
myPlugin
```
,
```
my_plugin
```
,
```
My-Plugin
```
,
```
plugin-
```

格式：kebab-case（仅小写字母、数字及连字符）
正则匹配：
```
^[a-z0-9]+(-[a-z0-9]+)*$
```

示例：

有效：
```
my-plugin
```
,
```
core-skills
```
,
```
elixir-tools
```
无效：
```
myPlugin
```
,
```
my_plugin
```
,
```
My-Plugin
```
,
```
plugin-
```

version

Format: Semantic versioning

Pattern:

^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$

Examples:

Valid:
```
1.0.0
```
,
```
2.1.3
```
,
```
1.0.0-beta.1
```
,
```
1.0.0+build.123
```
Invalid:
```
1.0
```
,
```
v1.0.0
```
,
```
1.0.0.0
```

格式：语义化版本规范

正则匹配：

^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$

示例：

有效：
```
1.0.0
```
,
```
2.1.3
```
,
```
1.0.0-beta.1
```
,
```
1.0.0+build.123
```
无效：
```
1.0
```
,
```
v1.0.0
```
,
```
1.0.0.0
```

license

Format: SPDX license identifier
Common values:
```
MIT
```
,
```
Apache-2.0
```
,
```
GPL-3.0
```
,
```
BSD-3-Clause
```
,
```
ISC
```
Reference: https://spdx.org/licenses/

格式：SPDX许可证标识符
常见值：
```
MIT
```
,
```
Apache-2.0
```
,
```
GPL-3.0
```
,
```
BSD-3-Clause
```
,
```
ISC
```
参考链接：https://spdx.org/licenses/

keywords

Format: Array of strings
Purpose: Discoverability, searchability, categorization
Recommendations: Use lowercase, be specific, include domain terms

格式：字符串数组
用途：提升插件可发现性、搜索性与分类效率
建议：使用小写字母，表述具体，包含领域相关术语

Paths (skills, commands, agents, hooks, mcpServers)

路径字段（skills, commands, agents, hooks, mcpServers）

Format: Relative paths from plugin root
Recommendations: Use
```
./
```
prefix for clarity
Skills: Array of directory paths containing SKILL.md files
Commands: Can be string (single path) or array of paths
Agents: Can be string (directory) or array of file paths

格式：相对于插件根目录的路径
建议：使用
```
./
```
前缀增强可读性
Skills：包含SKILL.md文件的目录路径数组
Commands：支持单个路径字符串或路径数组
Agents：支持单个目录路径字符串或文件路径数组

Invalid Fields in plugin.json

plugin.json 中的无效字段

The following fields are only valid in marketplace.json entries and must NOT appear in plugin.json:

```
dependencies
```
: Dependencies belong in marketplace entries, not plugin manifests
```
category
```
: Categorization is marketplace-level metadata
```
strict
```
: Controls marketplace behavior, not plugin definition
```
source
```
: Plugin location is defined in marketplace, not in plugin itself
```
tags
```
: Use
```
keywords
```
instead

以下字段仅在marketplace.json中有效，禁止出现在plugin.json中：

```
dependencies
```
：依赖关系应定义在marketplace条目而非插件清单中
```
category
```
：分类信息属于marketplace层面的元数据
```
strict
```
：控制marketplace行为，与插件定义无关
```
source
```
：插件位置由marketplace定义，无需在插件中指定
```
tags
```
：请使用
```
keywords
```
字段替代

Validation Workflow

验证流程

1. Schema Validation

1. Schema验证

Use the provided Nushell script to validate plugin.json:

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.nu .claude-plugin/plugin.json

This validates:

JSON syntax
Required field presence (name)
Kebab-case naming
Field type correctness
Path accessibility (for relative paths)
Invalid field detection

使用提供的Nushell脚本验证plugin.json：

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.nu .claude-plugin/plugin.json

该脚本会验证：

JSON语法正确性
必填字段（name）是否存在
名称是否符合kebab-case格式
字段类型是否正确
相对路径是否可访问
是否存在无效字段

2. Path Validation

2. 路径验证

Validate that referenced paths exist:

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin-paths.nu .claude-plugin/plugin.json

Checks:

Skills directories exist and contain SKILL.md
Command files/directories exist
Agent files/directories exist
Hooks configuration exists
MCP server configuration exists

验证所有引用路径是否存在：

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin-paths.nu .claude-plugin/plugin.json

检查内容：

Skills目录是否存在且包含SKILL.md文件
命令文件/目录是否存在
Agent文件/目录是否存在
Hooks配置是否存在
MCP服务器配置是否存在

3. Initialization Helper

3. 初始化助手

Generate a template plugin.json:

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/init-plugin.nu

Creates

.claude-plugin/plugin.json

with proper structure.

生成plugin.json模板：

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/init-plugin.nu

该命令会创建结构规范的

.claude-plugin/plugin.json

文件。

Best Practices

最佳实践

Naming Conventions

命名规范

Plugin name: Use descriptive kebab-case (e.g.,
```
elixir-phoenix
```
,
```
rust-tools
```
,
```
core-skills
```
)
Avoid generic names: Be specific about the plugin's purpose
Match directory name: Plugin name should match its directory name

插件名称：使用描述性的kebab-case格式（如
```
elixir-phoenix
```
,
```
rust-tools
```
,
```
core-skills
```
）
避免通用名称：明确插件用途，避免模糊命名
与目录名一致：插件名称应与其所在目录名称保持一致

Versioning Strategy

版本策略

Use semantic versioning (MAJOR.MINOR.PATCH)
Increment MAJOR for breaking changes
Increment MINOR for new features (backward compatible)
Increment PATCH for bug fixes
Use pre-release tags for beta versions (
```
1.0.0-beta.1
```
)

遵循语义化版本规范（MAJOR.MINOR.PATCH）
重大破坏性更新时递增MAJOR版本
新增向后兼容功能时递增MINOR版本
修复bug时递增PATCH版本
测试版本使用预发布标签（如
```
1.0.0-beta.1
```
）

Path Organization

路径组织

Recommended structure:

plugin-name/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── skill-one/
│   └── skill-two/
├── commands/
└── agents/

In plugin.json:

json

{
  "skills": [
    "./skills/skill-one",
    "./skills/skill-two"
  ],
  "commands": ["./commands"],
  "agents": ["./agents"]
}

推荐目录结构：

plugin-name/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── skill-one/
│   └── skill-two/
├── commands/
└── agents/

plugin.json中对应配置：

json

{
  "skills": [
    "./skills/skill-one",
    "./skills/skill-two"
  ],
  "commands": ["./commands"],
  "agents": ["./agents"]
}

Metadata Completeness

元数据完整性

Always include:

```
version
```
: Track plugin evolution
```
description
```
: Help users understand purpose
```
license
```
: Clarify usage terms
```
keywords
```
: Improve discoverability
```
repository
```
: Enable contributions

建议始终包含以下元数据：

```
version
```
：追踪插件迭代历史
```
description
```
：帮助用户快速理解插件用途
```
license
```
：明确使用条款
```
keywords
```
：提升插件可发现性
```
repository
```
：方便用户贡献代码

Author Information

作者信息

Include contact information for:

Bug reports
Feature requests
Contributions
Questions

提供作者联系方式，便于：

提交bug报告
提出功能需求
参与代码贡献
咨询相关问题

Common Validation Errors

常见验证错误

Error: Invalid kebab-case name

错误：名称不符合kebab-case格式

json

// ❌ Invalid
"name": "myPlugin"
"name": "my_plugin"
"name": "My-Plugin"

// ✅ Valid
"name": "my-plugin"
"name": "core-skills"

json

// ❌ 无效
"name": "myPlugin"
"name": "my_plugin"
"name": "My-Plugin"

// ✅ 有效
"name": "my-plugin"
"name": "core-skills"

Error: Invalid field for plugin.json

错误：plugin.json中包含无效字段

json

// ❌ Invalid (dependencies only in marketplace.json)
{
  "name": "my-plugin",
  "dependencies": ["other-plugin"]
}

// ✅ Valid
{
  "name": "my-plugin",
  "keywords": ["tool", "utility"]
}

json

// ❌ 无效（dependencies仅在marketplace.json中有效）
{
  "name": "my-plugin",
  "dependencies": ["other-plugin"]
}

// ✅ 有效
{
  "name": "my-plugin",
  "keywords": ["tool", "utility"]
}

Error: Skill path doesn't exist

错误：技能路径不存在

json

// ❌ Invalid (path not found)
"skills": ["./skills/nonexistent"]

// ✅ Valid (path exists with SKILL.md)
"skills": ["./skills/my-skill"]

json

// ❌ 无效（路径不存在）
"skills": ["./skills/nonexistent"]

// ✅ 有效（路径存在且包含SKILL.md）
"skills": ["./skills/my-skill"]

Error: Invalid version format

错误：版本格式无效

json

// ❌ Invalid
"version": "1.0"
"version": "v1.0.0"

// ✅ Valid
"version": "1.0.0"
"version": "2.1.3-beta.1"

json

// ❌ 无效
"version": "1.0"
"version": "v1.0.0"

// ✅ 有效
"version": "1.0.0"
"version": "2.1.3-beta.1"

Creating a New Plugin

创建新插件

Step 1: Initialize Directory Structure

步骤1：初始化目录结构

bash

mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/skills

bash

mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/skills

Step 2: Create plugin.json

步骤2：创建plugin.json

Use the initialization script:

bash

cd my-plugin
nu ${CLAUDE_PLUGIN_ROOT}/scripts/init-plugin.nu

Or create manually:

json

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "My plugin description",
  "author": {
    "name": "Your Name"
  },
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": []
}

使用初始化脚本：

bash

cd my-plugin
nu ${CLAUDE_PLUGIN_ROOT}/scripts/init-plugin.nu

或手动创建：

json

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "My plugin description",
  "author": {
    "name": "Your Name"
  },
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": []
}

Step 3: Add Skills

步骤3：添加技能

Create skill directory:
```
mkdir -p skills/my-skill
```
Create SKILL.md in skill directory
Add to plugin.json:

json

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

创建技能目录：
```
mkdir -p skills/my-skill
```
在技能目录中创建SKILL.md文件
在plugin.json中添加路径：

json

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

Step 4: Validate

步骤4：验证

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.nu .claude-plugin/plugin.json

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.nu .claude-plugin/plugin.json

Step 5: Test

步骤5：测试

Install locally to test:

bash

claude-code install ./

本地安装插件进行测试：

bash

claude-code install ./

Hooks Configuration

Hooks配置

Hooks can be inline or referenced:

Inline:

json

{
  "hooks": {
    "onInstall": "./scripts/install.sh",
    "onUninstall": "./scripts/uninstall.sh"
  }
}

Referenced:

json

{
  "hooks": "./config/hooks.json"
}

Hooks支持内联配置或文件引用两种方式：

内联配置：

json

{
  "hooks": {
    "onInstall": "./scripts/install.sh",
    "onUninstall": "./scripts/uninstall.sh"
  }
}

文件引用：

json

{
  "hooks": "./config/hooks.json"
}

MCP Servers Configuration

MCP服务器配置

MCP servers can be inline or referenced:

Inline:

json

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["./workspace"]
    }
  }
}

Referenced:

json

{
  "mcpServers": "./mcp-config.json"
}

MCP服务器支持内联配置或文件引用两种方式：

内联配置：

json

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["./workspace"]
    }
  }
}

文件引用：

json

{
  "mcpServers": "./mcp-config.json"
}

Troubleshooting

故障排查

Plugin Not Loading

插件无法加载

Verify plugin.json exists at
```
.claude-plugin/plugin.json
```
Check JSON syntax is valid
Ensure name field is present and kebab-case
Validate all path references exist

确认plugin.json存在于
```
.claude-plugin/plugin.json
```
路径
检查JSON语法是否正确
确保name字段存在且符合kebab-case格式
验证所有引用路径均存在

Skills Not Found

技能无法被识别

Check skill paths in plugin.json match actual directories
Ensure each skill directory contains SKILL.md file
Verify paths use relative format (
```
./skills/name
```
)

检查plugin.json中的技能路径与实际目录是否一致
确保每个技能目录中都包含SKILL.md文件
验证路径使用相对格式（如
```
./skills/name
```
）

Commands Not Appearing

命令未显示

Verify command paths exist
Check commands are .md files or directories containing .md files
Ensure paths are relative to plugin root

验证命令路径是否存在
检查命令是否为.md文件或包含.md文件的目录
确保路径相对于插件根目录

Validation Fails

验证失败

Run validation with verbose output:

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.nu .claude-plugin/plugin.json --verbose

使用 verbose 模式运行验证脚本查看详细信息：

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.nu .claude-plugin/plugin.json --verbose

References

参考资料

For detailed schema specifications and examples, see:

```
references/plugin-schema.md
```
: Complete JSON schema specification
```
references/plugin-examples.md
```
: Real-world plugin.json examples

如需查看详细Schema规范及示例，请参考：

```
references/plugin-schema.md
```
：完整JSON Schema规范
```
references/plugin-examples.md
```
：真实场景下的plugin.json示例

Script Usage

脚本使用说明

All validation and utility scripts are located in

scripts/

```
validate-plugin.nu
```
: Complete plugin.json validation
```
validate-plugin-paths.nu
```
: Verify all referenced paths exist
```
init-plugin.nu
```
: Generate plugin.json template
```
format-plugin.nu
```
: Format and sort plugin.json

Execute scripts with:

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/[script-name].nu [args]

所有验证与工具脚本均位于

scripts/

目录下：

```
validate-plugin.nu
```
：完整的plugin.json验证脚本
```
validate-plugin-paths.nu
```
：验证所有引用路径的存在性
```
init-plugin.nu
```
：生成plugin.json模板
```
format-plugin.nu
```
：格式化并排序plugin.json内容

执行脚本方式：

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/[script-name].nu [args]