Guide for creating Claude Code plugins with proper structure, metadata, and components. This skill should be used when creating plugins, writing manifests, or setting up marketplaces.
/plugin marketplace add charlesjones-dev/claude-code-plugins-dev/plugin install ai-plugins@claude-code-plugins-devThis skill inherits all available tools. When active, it can use any tool Claude has access to.
This skill provides guidance for creating Claude Code plugins, including structure, manifests, components (commands, agents, skills, hooks, MCP servers), and marketplace distribution.
This skill should be used when:
Plugins are extensions that add custom functionality to Claude Code, shareable across projects and teams. They can include:
Plugin:
.claude-plugin/plugin.json manifestMarketplace:
.claude-plugin/marketplace.json manifestEvery plugin must follow this standard structure:
plugin-name/
├── .claude-plugin/
│ └── plugin.json # Required: Plugin manifest
├── commands/ # Optional: Slash commands
│ ├── command-one.md
│ └── command-two.md
├── agents/ # Optional: Custom agents
│ └── agent-name.md
├── skills/ # Optional: Agent skills
│ ├── skill-one/
│ │ └── SKILL.md
│ └── skill-two/
│ └── SKILL.md
├── hooks/ # Optional: Event handlers
│ └── hooks.json
├── .mcp.json # Optional: MCP server config
├── scripts/ # Optional: Utility scripts
├── README.md # Recommended: Documentation
└── LICENSE # Recommended: License file
Critical Requirements:
.claude-plugin/plugin.json file is REQUIRED for all plugins.claude-plugin/my-plugin, not MyPlugin or my_plugin)The plugin.json file is your plugin's core configuration. It must be located at .claude-plugin/plugin.json.
{
"name": "plugin-name"
}
Field Specifications:
"deployment-tools", "ai-security", "git-helpers"{
"name": "plugin-name",
"version": "1.0.0",
"description": "Brief explanation of what this plugin does",
"author": {
"name": "Author Name",
"email": "author@example.com",
"url": "https://example.com"
},
"homepage": "https://github.com/owner/plugin-repo",
"repository": "https://github.com/owner/plugin-repo",
"license": "MIT",
"keywords": ["keyword1", "keyword2", "keyword3"]
}
Field Specifications:
version (recommended)
"2.1.0"description (recommended)
author (recommended)
homepage (recommended)
repository (recommended)
license (recommended)
"MIT", "Apache-2.0", "GPL-3.0")keywords (recommended)
["git", "automation", "security", "devops"]{
"name": "plugin-name",
"commands": "./custom-commands",
"agents": "./custom-agents/agent.md",
"hooks": "./custom-hooks/hooks.json",
"mcpServers": "./.mcp.json"
}
Path Configuration Rules:
./${CLAUDE_PLUGIN_ROOT} environment variable for absolute path references in hooks and MCP configsWhen to Use Custom Paths:
Commands are markdown files in the commands/ directory that define interactive workflows.
File Structure:
commands/
├── setup-project.md
└── deploy-staging.md
Command File Format:
# Command Title
Brief description of what this command does.
## Instructions
Step-by-step instructions for Claude Code to execute when this command is invoked.
1. First step
2. Second step
3. Third step
## Important Notes
Any constraints, requirements, or special considerations.
Best Practices:
When to Use Commands vs Skills:
Agents are markdown files in the agents/ directory that describe specialized Claude instances.
File Structure:
agents/
└── security-auditor.md
Agent File Format:
---
description: Specialized agent for security auditing and vulnerability detection
---
# Security Auditor Agent
This agent specializes in identifying security vulnerabilities, reviewing authentication mechanisms, and conducting security audits.
## Capabilities
- Identify SQL injection vulnerabilities
- Review authentication and authorization flows
- Validate input sanitization
- Assess data protection measures
- Generate security audit reports
## When to Invoke
Use this agent when:
- Implementing authentication flows
- Reviewing security-sensitive code
- Conducting pre-deployment security audits
Best Practices:
Skills are directories in the skills/ folder containing SKILL.md files that provide just-in-time expertise.
File Structure:
skills/
├── brand-guidelines/
│ └── SKILL.md
└── security-standards/
├── SKILL.md
└── references/
└── standards.md
SKILL.md Format:
---
name: Skill Name
description: Guide for [topic]. This skill should be used when [specific use cases] (max 200 chars)
---
# Skill Name Skill
This skill provides guidance on [topic].
## When to Use This Skill
This skill should be used when:
- [Use case 1]
- [Use case 2]
## Guidelines
[Core expertise and instructions]
Best Practices:
skills-scaffold skill for comprehensive skill creation guidanceHooks are JSON configurations in hooks/hooks.json that execute in response to events.
File Location:
hooks/
└── hooks.json
Hook Configuration Format:
{
"hooks": [
{
"name": "pre-commit-check",
"event": "PreToolUse",
"tool": "Bash",
"script": "${CLAUDE_PLUGIN_ROOT}/scripts/pre-commit.sh",
"blockOnNonZeroExit": true
},
{
"name": "session-setup",
"event": "SessionStart",
"script": "${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh"
}
]
}
Event Types:
PreToolUse: Before a tool is executedPostToolUse: After a tool completesUserPromptSubmit: When user submits a promptNotification: When a notification is triggeredStop: When execution stopsSessionStart: When a new session beginsBest Practices:
${CLAUDE_PLUGIN_ROOT} for script pathsblockOnNonZeroExit: true to halt execution on errorsMCP servers integrate external tools via the Model Context Protocol.
File Location:
.mcp.json
MCP Configuration Format:
{
"mcpServers": {
"server-name": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/mcp-server/index.js"],
"env": {
"API_KEY": "${API_KEY}"
}
}
}
}
Best Practices:
${CLAUDE_PLUGIN_ROOT} for script pathsBefore creating a plugin, determine:
Design Principle: One plugin = one purpose. When solving multiple unrelated problems, create multiple plugins.
mkdir -p plugin-name/.claude-plugin
mkdir -p plugin-name/commands # If needed
mkdir -p plugin-name/agents # If needed
mkdir -p plugin-name/skills # If needed
mkdir -p plugin-name/hooks # If needed
mkdir -p plugin-name/scripts # If needed
Create .claude-plugin/plugin.json:
{
"name": "plugin-name",
"version": "1.0.0",
"description": "Brief description of plugin purpose",
"author": {
"name": "Your Name",
"url": "https://yoursite.com"
},
"repository": "https://github.com/owner/plugin-repo",
"license": "MIT",
"keywords": ["keyword1", "keyword2"]
}
Add the components your plugin needs:
For Commands:
commands/ directoryFor Agents:
agents/ directoryFor Skills:
skills/{skill-name}/SKILL.md with YAML frontmatterskills-scaffold skill guidanceFor Hooks:
hooks/hooks.json configurationscripts/ directory${CLAUDE_PLUGIN_ROOT} for pathsFor MCP Servers:
.mcp.json configurationCreate a comprehensive README.md:
# Plugin Name
Brief description of what this plugin does.
## Features
- Feature 1
- Feature 2
## Installation
\`\`\`bash
/plugin marketplace add owner/repo
/plugin install plugin-name@marketplace-name
\`\`\`
## Usage
### Commands
- \`/command-name\`: Description of what it does
### Skills
- \`skill-name\`: Description of expertise provided
## Configuration
Any required setup or environment variables.
## License
License information.
Before distribution:
Validate JSON syntax
# Check plugin.json is valid JSON
cat .claude-plugin/plugin.json | jq .
Test locally
# Add as local marketplace
/plugin marketplace add ./path/to/plugin-parent-directory
# Install the plugin
/plugin install plugin-name@marketplace-name
Test all components
Review security
See Marketplace Distribution section below.
Follow Semantic Versioning:
When to Bump Version:
Version Update Workflow:
.claude-plugin/plugin.jsonv1.2.0)A marketplace is a repository that catalogs multiple plugins.
Directory Structure:
marketplace-repo/
├── .claude-plugin/
│ └── marketplace.json
├── plugins/ # If using local plugins
│ ├── plugin-one/
│ └── plugin-two/
└── README.md
Marketplace Manifest (.claude-plugin/marketplace.json):
{
"name": "marketplace-name",
"owner": {
"name": "Your Name",
"email": "you@example.com"
},
"metadata": {
"description": "Brief description of this marketplace",
"version": "1.0.0",
"pluginRoot": "./plugins"
},
"plugins": [
{
"name": "plugin-one",
"source": "./plugins/plugin-one",
"description": "What plugin-one does",
"version": "1.0.0",
"author": {
"name": "Author Name",
"url": "https://example.com"
},
"repository": "https://github.com/owner/plugin-one",
"license": "MIT",
"keywords": ["keyword1", "keyword2"]
}
]
}
Required Fields:
name: Unique marketplace identifier (kebab-case)owner: Maintainer information with name and emailplugins: Array of plugin entriesOptional Metadata:
metadata.description: Marketplace overviewmetadata.version: Marketplace versionmetadata.pluginRoot: Base path for relative plugin sources (e.g., "./plugins")Relative Paths (same repository):
{
"name": "my-plugin",
"source": "./plugins/my-plugin"
}
pluginRoot metadata field sets the base directoryGitHub Repositories:
{
"name": "github-plugin",
"source": {
"source": "github",
"repo": "owner/plugin-repo"
}
}
Git Repositories:
{
"name": "git-plugin",
"source": {
"source": "url",
"url": "https://gitlab.com/team/plugin.git"
}
}
GitHub (Recommended):
.claude-plugin/marketplace.json at rootpluginRoot)source objects)/plugin marketplace add owner/repo
Other Git Services:
/plugin marketplace add https://gitlab.com/company/plugins.git
Local Development:
/plugin marketplace add ./my-local-marketplace
List configured marketplaces:
/plugin marketplace list
Update marketplace metadata:
/plugin marketplace update marketplace-name
Remove a marketplace:
/plugin marketplace remove marketplace-name
Install plugins:
/plugin install plugin-name@marketplace-name
Configure .claude/settings.json in repositories to auto-install marketplaces:
{
"extraKnownMarketplaces": {
"team-tools": {
"source": {
"source": "github",
"repo": "your-org/claude-plugins"
}
}
}
}
When team members trust the folder, configured marketplaces install automatically.
Use Case: Streamline common development tasks (git, deployments, testing)
Structure:
Example:
git-helpers/
├── .claude-plugin/plugin.json
├── commands/
│ ├── commit-push.md
│ └── setup-repo.md
├── hooks/
│ └── hooks.json
└── scripts/
└── pre-commit.sh
Use Case: Provide specialized knowledge (security, performance, architecture)
Structure:
Example:
security-expert/
├── .claude-plugin/plugin.json
├── agents/
│ └── security-auditor.md
├── skills/
│ ├── security-standards/
│ │ └── SKILL.md
│ └── owasp-guidelines/
│ └── SKILL.md
└── commands/
└── security-audit.md
Use Case: Integrate external services (Azure DevOps, Jira, Slack)
Structure:
Example:
ado-integration/
├── .claude-plugin/plugin.json
├── .mcp.json
├── commands/
│ └── ado-init.md
├── skills/
│ └── ado-work-items/
│ └── SKILL.md
└── mcp-server/
└── index.js
Use Case: Generate boilerplate code and project structure
Structure:
Example:
project-scaffold/
├── .claude-plugin/plugin.json
├── commands/
│ ├── create-react-app.md
│ └── create-api.md
├── skills/
│ └── architecture-patterns/
│ └── SKILL.md
└── templates/
├── react-component.tsx
└── api-endpoint.ts
Good Examples:
git-helpers (git automation)security-auditor (security scanning)deployment-tools (deployment workflows)Bad Example:
developer-tools (git + security + deployment + testing + ...)Avoid:
my-plugin)my-command.md)my-skill/)${CLAUDE_PLUGIN_ROOT} in hooks and MCP configs.env.example files for templatesplugin-name/
├── scripts/ # Executable scripts for hooks/automation
├── templates/ # Template files for scaffolding
├── examples/ # Example configurations
└── docs/ # Additional documentation
Before distributing a plugin, verify:
Structure:
.claude-plugin/plugin.json exists with required fields.claude-plugin/)Manifest:
Components:
Documentation:
Quality:
jq)Marketplace (if applicable):
Possible Causes:
.claude-plugin/plugin.json.claude-plugin/ instead of plugin rootSolution:
.claude-plugin/plugin.jsoncat .claude-plugin/plugin.json | jq .Possible Causes:
Solution:
commands/ directory at plugin root.md./Possible Causes:
SKILL.md file (case-sensitive)Solution:
SKILL.md (uppercase)skills-scaffold skill for detailsPossible Causes:
${CLAUDE_PLUGIN_ROOT} environment variableSolution:
${CLAUDE_PLUGIN_ROOT} for all script pathschmod +x scripts/*.shPossible Causes:
Solution:
Possible Causes:
Solution:
Plugins can reference each other's capabilities:
For git automation, the git-helpers plugin provides comprehensive commands.
For security standards, refer to the security-expert plugin's skills.
Best Practice: Keep plugins independent where possible, but document complementary plugins in README.md.
Plugins can include scripts in different languages:
scripts/
├── python/
│ └── analyzer.py
├── javascript/
│ └── formatter.js
└── shell/
└── deploy.sh
Best Practice: Document runtime requirements (Python version, Node version) in README.md and plugin.json dependencies field.
Create meta-plugins that generate other plugins:
Example: The ai-plugins plugin includes:
/plugins-scaffold command for generating plugin structureplugins-scaffold skill for plugin development guidanceskills-scaffold skill for skill creation guidanceUse environment variables for configuration:
{
"mcpServers": {
"api-service": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
"env": {
"API_URL": "${API_URL}",
"API_KEY": "${API_KEY}",
"ENVIRONMENT": "${ENVIRONMENT:-development}"
}
}
}
}
Best Practice: Provide .env.example file with required variables.
Creating effective Claude Code plugins requires:
Following these guidelines will result in well-structured plugins that enhance Claude Code's capabilities and provide value to users.
For skill creation specifically, the skills-scaffold skill provides detailed guidance.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.