buildingplugins

name	buildingplugins
description	Use when creating, developing, or troubleshooting Claude Code plugins, skills, hooks, agents, or MCP servers. For questions like "How do I create a plugin?", "What goes in plugin.json?", "How do skills work?", or "Help me build a marketplace".
allowed-tools	Read, Glob, Grep, Write, Edit, Bash
user-invocable	true

Building Plugins for Claude Code

You are an expert in Claude Code plugin development. Help users create well-structured plugins, skills, hooks, agents, and MCP configurations following Anthropic's best practices.

Core Principles

1. Progressive Disclosure - Keep main files lean (<500 lines), reference detailed docs in supporting files
2. Clear Descriptions - Use trigger phrases ("Use when...", "For...") so Claude auto-discovers components
3. Modular Design - Separate concerns into commands/, skills/, agents/, hooks/
4. Security First - Never hardcode secrets, validate inputs, use environment variables

Plugin Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Manifest (REQUIRED)
├── commands/                # Slash commands
├── skills/                  # Skills with SKILL.md
├── agents/                  # Sub-agents
├── hooks/                   # hooks.json
├── .mcp.json               # MCP servers
└── README.md               # Documentation

Quick Reference

plugin.json (Required Fields)

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "What this plugin does",
  "skills": "./skills/",
  "commands": "./commands/"
}

SKILL.md Frontmatter

---
name: skill-name
description: Use when [trigger condition]. For [use cases].
allowed-tools: Read, Glob, Grep
user-invocable: true
---

Agent Frontmatter

---
name: agent-name
description: Expert in [domain]. Use for [tasks].
tools: Read, Grep, Glob, Bash
model: sonnet
---

Slash Command Frontmatter

---
description: What this command does
---

Detailed References

For comprehensive documentation on specific topics, see the reference files:

• Plugin Reference - Complete plugin.json schema, installation scopes, validation
• Skills Reference - All frontmatter fields, progressive disclosure patterns
• Hooks Reference - Hook events, matchers, response formats
• Agents Reference - Agent configuration, permission modes, built-in agents
• MCP Reference - Server types, configuration, environment variables
• Marketplace Reference - Creating and distributing marketplaces

Common Tasks

Creating a New Plugin

1. Create directory structure with .claude-plugin/plugin.json
2. Add skills in skills/skill-name/SKILL.md
3. Add commands in commands/command-name.md
4. Test with claude --plugin-dir ./my-plugin
5. Validate with claude plugin validate .

Creating a Skill

1. Create skills/my-skill/SKILL.md
2. Add frontmatter with name, description, allowed-tools
3. Write concise instructions (aim for <500 lines)
4. Add supporting files for detailed references
5. Test by invoking the skill

Adding Hooks

1. Create hooks/hooks.json or add to plugin.json
2. Define event matchers (PreToolUse, PostToolUse, Stop, etc.)
3. Specify hook type (command or prompt)
4. Test hook behavior thoroughly

Creating a Marketplace

1. Create marketplace.json with name, owner, metadata
2. Add plugins array with source paths
3. Test locally: /plugin marketplace add ./my-marketplace
4. Distribute via GitHub or Git URL

Best Practices Checklist

• Plugin name is lowercase with hyphens, 3-64 characters
• Description includes trigger phrases for auto-discovery
• Secrets use environment variables, never hardcoded
• Main files are concise, details in reference files
• Semantic versioning (MAJOR.MINOR.PATCH)
• Comprehensive README with examples
• Tested locally before distribution