Guide for creating and validating Claude Code plugin.json files with schema validation tools
Creates and validates plugin.json files for Claude Code plugins with schema compliance checking. Use when creating `.claude-plugin/plugin.json` files or troubleshooting plugin configuration issues.
/plugin marketplace add vinnie357/claude-skills/plugin install claude-code@vinnie357This skill is limited to using the following tools:
references/plugin-schema.mdscripts/format-plugin.nuscripts/init-plugin.nuscripts/validate-plugin.nuGuide for creating, validating, and managing plugin.json files for Claude Code plugins. Includes schema validation, best practices, and automated tools.
Activate this skill when:
.claude-plugin/plugin.json filesAll plugin manifests must be located at .claude-plugin/plugin.json within the plugin directory.
{
"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"]
}
name: Plugin identifier (kebab-case, lowercase alphanumeric and hyphens only)Metadata:
version: Semantic version number (recommended)description: Brief explanation of plugin functionalitylicense: SPDX license identifier (e.g., MIT, Apache-2.0)keywords: Array of searchability and categorization tagshomepage: Documentation or project URLrepository: Source control URLAuthor Information:
author.name: Creator nameauthor.email: Contact emailauthor.url: Personal or organization websiteComponent Paths:
skills: Array of skill directory paths (relative to plugin root)commands: String path or array of command file/directory pathsagents: String path or array of agent file pathshooks: String path to hooks.json or hooks configuration objectmcpServers: String path to MCP config or configuration object^[a-z0-9]+(-[a-z0-9]+)*$my-plugin, core-skills, elixir-toolsmyPlugin, my_plugin, My-Plugin, plugin-^[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.1231.0, v1.0.0, 1.0.0.0MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, ISC./ prefix for clarityThe following fields are only valid in marketplace.json entries and must NOT appear in plugin.json:
dependencies: Dependencies belong in marketplace entries, not plugin manifestscategory: Categorization is marketplace-level metadatastrict: Controls marketplace behavior, not plugin definitionsource: Plugin location is defined in marketplace, not in plugin itselftags: Use keywords insteadUse the provided Nushell script to validate plugin.json:
nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.nu .claude-plugin/plugin.json
This validates:
Validate that referenced paths exist:
nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin-paths.nu .claude-plugin/plugin.json
Checks:
Generate a template plugin.json:
nu ${CLAUDE_PLUGIN_ROOT}/scripts/init-plugin.nu
Creates .claude-plugin/plugin.json with proper structure.
elixir-phoenix, rust-tools, core-skills)1.0.0-beta.1)Recommended structure:
plugin-name/
├── .claude-plugin/
│ └── plugin.json
├── skills/
│ ├── skill-one/
│ └── skill-two/
├── commands/
└── agents/
In plugin.json:
{
"skills": [
"./skills/skill-one",
"./skills/skill-two"
],
"commands": ["./commands"],
"agents": ["./agents"]
}
Always include:
version: Track plugin evolutiondescription: Help users understand purposelicense: Clarify usage termskeywords: Improve discoverabilityrepository: Enable contributionsInclude contact information for:
// ❌ Invalid
"name": "myPlugin"
"name": "my_plugin"
"name": "My-Plugin"
// ✅ Valid
"name": "my-plugin"
"name": "core-skills"
// ❌ Invalid (dependencies only in marketplace.json)
{
"name": "my-plugin",
"dependencies": ["other-plugin"]
}
// ✅ Valid
{
"name": "my-plugin",
"keywords": ["tool", "utility"]
}
// ❌ Invalid (path not found)
"skills": ["./skills/nonexistent"]
// ✅ Valid (path exists with SKILL.md)
"skills": ["./skills/my-skill"]
// ❌ Invalid
"version": "1.0"
"version": "v1.0.0"
// ✅ Valid
"version": "1.0.0"
"version": "2.1.3-beta.1"
mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/skills
Use the initialization script:
cd my-plugin
nu ${CLAUDE_PLUGIN_ROOT}/scripts/init-plugin.nu
Or create manually:
{
"name": "my-plugin",
"version": "0.1.0",
"description": "My plugin description",
"author": {
"name": "Your Name"
},
"license": "MIT",
"keywords": ["keyword1", "keyword2"],
"skills": []
}
mkdir -p skills/my-skill{
"skills": ["./skills/my-skill"]
}
nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.nu .claude-plugin/plugin.json
Install locally to test:
claude-code install ./
Hooks can be inline or referenced:
Inline:
{
"hooks": {
"onInstall": "./scripts/install.sh",
"onUninstall": "./scripts/uninstall.sh"
}
}
Referenced:
{
"hooks": "./config/hooks.json"
}
MCP servers can be inline or referenced:
Inline:
{
"mcpServers": {
"filesystem": {
"command": "mcp-server-filesystem",
"args": ["./workspace"]
}
}
}
Referenced:
{
"mcpServers": "./mcp-config.json"
}
.claude-plugin/plugin.json./skills/name)Run validation with verbose output:
nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.nu .claude-plugin/plugin.json --verbose
For detailed schema specifications and examples, see:
references/plugin-schema.md: Complete JSON schema specificationreferences/plugin-examples.md: Real-world plugin.json examplesAll validation and utility scripts are located in scripts/:
validate-plugin.nu: Complete plugin.json validationvalidate-plugin-paths.nu: Verify all referenced paths existinit-plugin.nu: Generate plugin.json templateformat-plugin.nu: Format and sort plugin.jsonExecute scripts with:
nu ${CLAUDE_PLUGIN_ROOT}/scripts/[script-name].nu [args]
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.