Expert guidance for developing, structuring, and maintaining Claude Code plugin marketplaces with multi-plugin architecture, agent teams, and layered documentation patterns.
Expert guidance for developing Claude Code plugin marketplaces following the Anthropic marketplace pattern. Helps you create multi-plugin repositories with specialized agent teams, slash commands, skills, and layered documentation.
This skill provides comprehensive guidance for:
When working with plugin marketplaces, follow this structure:
```
marketplace-repo/
├── .claude-plugin/
│ └── marketplace.json # Marketplace manifest
├── plugins/
│ └── plugin-name/
│ ├── .claude-plugin/
│ │ ├── plugin.json # Minimal plugin metadata
│ │ └── marketplace.json # Standalone manifest (optional)
│ ├── agents/ # Agent definitions (.md files)
│ ├── commands/ # Slash commands (.md files)
│ ├── skills/ # Skill directories
│ ├── docs/ # Process documentation
│ │ ├── standing-orders.md
│ │ ├── team.md
│ │ └── processes/
│ └── README.md
├── README.md
├── LICENSE
└── .gitignore
```
**File:** `.claude-plugin/marketplace.json`
**Required Structure:**
```json
{
"name": "marketplace-name",
"version": "1.0.0",
"owner": {
"name": "Your Name",
"email": "[email protected]"
},
"plugins": [
{
"name": "plugin-name",
"description": "Plugin description",
"version": "0.1.0",
"author": {
"name": "Your Name",
"email": "[email protected]"
},
"source": "./plugins/plugin-name",
"category": "Development"
}
]
}
```
**Critical Rules:**
**File:** `plugins/*/. claude-plugin/plugin.json`
**Required Structure:**
```json
{
"name": "plugin-name",
"version": "0.1.0",
"description": "Plugin description",
"author": {
"name": "Your Name",
"email": "[email protected]"
}
}
```
**Critical Rules:**
Plugins use a two-layer configuration system:
**Layer 1: Plugin Defaults (Global)**
**Layer 2: Project Overrides (Local)**
Agents check both locations:
1. Check `.claude/docs/[file].md` in project (if exists)
2. Fall back to plugin path
**Known Issue:** Due to Claude Code issue #9354, `${CLAUDE_PLUGIN_ROOT}` doesn't work in agent/command markdown files. Use hardcoded paths as workaround: `~/.claude/plugins/marketplaces/[marketplace]/plugins/[plugin]/`
```bash
mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins
cat > my-marketplace/.claude-plugin/marketplace.json << 'EOF'
{
"name": "my-marketplace",
"version": "1.0.0",
"owner": {
"name": "Your Name",
"email": "[email protected]"
},
"plugins": []
}
EOF
cat > my-marketplace/README.md << 'EOF'
Claude Code plugin marketplace description.
(List plugins here)
```bash
/plugin marketplace add username/my-marketplace
```
EOF
```
```bash
mkdir -p plugins/new-plugin/.claude-plugin
mkdir -p plugins/new-plugin/{agents,commands,skills,docs/processes}
cat > plugins/new-plugin/.claude-plugin/plugin.json << 'EOF'
{
"name": "new-plugin",
"version": "0.1.0",
"description": "Plugin description",
"author": {
"name": "Your Name",
"email": "[email protected]"
}
}
EOF
cat > plugins/new-plugin/README.md << 'EOF'
```bash
/plugin install new-plugin@my-marketplace
```
EOF
```
**File:** `plugins/[plugin]/agents/agent-name.md`
```markdown
---
name: agent-name
description: "Agent purpose"
model: sonnet-4.5
color: blue
---
Check for project-specific rules:
1. Primary responsibility
2. Secondary responsibility
3. Quality checks
1. Read relevant process documentation
2. Analyze requirements
3. Execute task following rules
4. Validate output
5. Report completion
```
**File:** `plugins/[plugin]/commands/command-name.md`
```markdown
---
allowed-tools: ["*"]
argument-hint: "[description]"
description: "Command purpose"
---
Execute specific workflow task.
1. Check process documentation
2. Validate inputs
3. Execute following established patterns
4. Verify output quality
Expected deliverable format.
```
**File:** `plugins/[plugin]/docs/processes/process-name.md`
```markdown
Description of this process and when to use it.
1. **Rule Category**
- Specific guideline
- Example or pattern
- Anti-pattern to avoid
2. **Another Category**
- Additional guidelines
- Best practices
```
Example showing correct approach
```
```
Example showing what to avoid
```
```
```bash
cp -r my-marketplace ~/.claude/plugins/repos/my-marketplace
/plugin marketplace add username/my-marketplace
/plugin install plugin-name@my-marketplace
/plugin
/command-name
```
```bash
cp -r . ~/.claude/plugins/repos/my-marketplace
```
1. Create agent file with proper frontmatter
2. Include documentation lookup section (layered docs)
3. Define clear responsibilities
4. Reference process documentation
5. Update `docs/team.md` with agent description
1. Create command file with frontmatter (allowed-tools, argument-hint, description)
2. Define task and requirements clearly
3. Reference relevant process docs
4. Update plugin README with command listing
1. Create skill directory with SKILL.md
2. Follow KillerSkills marketplace format
3. Include clear installation instructions
4. Document skill capabilities and usage
**Error:** "Invalid author field"
**Error:** "Unknown property: displayName"
**Error:** "Unknown property: agents/commands/skills"
**Issue:** Agent can't find process docs
**Issue:** Plugin shows as available but won't install
1. **Keep plugin.json minimal** - Only name, version, description, author
2. **Use layered documentation** - Plugin defaults + project overrides
3. **Version consistently** - Update both plugin.json and marketplace.json
4. **Test locally first** - Copy to plugins directory before pushing
5. **Follow naming conventions** - Use kebab-case for all identifiers
6. **Self-contained plugins** - No cross-plugin dependencies
7. **Document thoroughly** - Clear README for each plugin
8. **Update agent counts** - Keep documentation accurate when adding/removing components
```bash
/plugin marketplace add username/marketplace-name
/plugin install plugin-name@marketplace-name
/plugin
/help
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/claude-code-plugin-marketplace-development/raw