Here is the claude.md file I put in my plugin-development root folder. Then I create a new folder for each new plugin within this directory. Each new version of your plugin is placed in a separate, public, git repo as a Plugin Marketplace.
# Claude Plugins Development Warehouse This repo is a development warehouse for Claude Code plugins. Each top-level directory is an independent plugin under development before publication to an official marketplace. ## Repo Structure ``` claude-plugins-dev/ ├── CLAUDE.md ← You are here (development guide) ├── marketplace.json ← Local marketplace registry for testing ├── bulk-messenger-minimal/ ← SMS composer plugin (active) ├── bulk-messenger-plugin/ ← Full messaging plugin (stable) ├── notion-crm-plugin/ ← Notion CRM with TypeScript MCP server └── [new-plugin]/ ← Create new plugins at root level ``` ## Quick Reference - **Official docs**: https://code.claude.com/docs/en/plugins-reference - **Official examples**: https://github.com/anthropics/claude-code/tree/main/plugins - **Plugin dev tool**: Use the `plugin-dev` plugin skills for guided creation - **Test a plugin locally**: `claude --plugin-dir ./my-plugin` - **Validate**: `/plugin validate` or `claude plugin validate` --- # Plugin Development Guide This guide is the authoritative reference for coding agents creating Claude Code plugins in this repo. Follow these patterns exactly. ## 1. Plugin Directory Layout Every plugin follows this standard structure. Components live at the plugin root, NOT inside `.claude-plugin/`. ``` my-plugin/ ├── .claude-plugin/ │ └── plugin.json # Manifest (only file in this dir) ├── skills/ # Skills (directories with SKILL.md) │ ├── my-skill/ │ │ └── SKILL.md │ └── another-skill/ │ ├── SKILL.md │ └── scripts/ # Optional supporting files ├── agents/ # Subagents (markdown files) │ └── my-agent.md ├── commands/ # Slash commands (markdown files) │ └── my-command.md ├── hooks/ # Event handlers │ ├── hooks.json # Hook configuration │ └── my-hook-script.sh # Hook scripts ├── scripts/ # Utility scripts │ └── helper.sh ├── .mcp.json # MCP server config (optional) ├── .lsp.json # LSP server config (optional) ├── LICENSE └── README.md ``` **Critical rule**: `.claude-plugin/` contains ONLY `plugin.json`. Everything else goes at the plugin root. ## 2. Plugin Manifest (`plugin.json`) Located at `.claude-plugin/plugin.json`. The `name` field is required; everything else is optional. Auto-discovery finds components in default locations without explicit paths. ```json { "name": "my-plugin", "version": "1.0.0", "description": "Brief, clear description of what this plugin does", "author": { "name": "Author Name", "email": "author@example.com" } } ``` **Naming**: Use kebab-case, no spaces. The name namespaces all components (e.g., `my-plugin:my-agent`). **Version**: Follow semver (`MAJOR.MINOR.PATCH`). Start at `1.0.0`. **When to add component paths**: Only if components live outside default directories: ```json { "name": "my-plugin", "commands": ["./custom/commands/special.md"], "agents": "./custom/agents/", "skills": "./custom/skills/", "hooks": "./config/hooks.json", "mcpServers": "./mcp-config.json" } ``` Paths are relative to plugin root and must start with `./`. Custom paths **supplement** defaults, they don't replace them. ## 3. Skills Skills are conversational workflow definitions, not code. They teach Claude how to perform specific tasks. ### File Structure ``` skills/ └── my-skill/ └── SKILL.md ``` ### SKILL.md Format ```markdown --- name: my-skill description: >- Concise description of what this skill does. Include trigger phrases the user might say so Claude knows when to invoke this skill. --- ## Purpose What this skill accomplishes and when to use it. ## Workflow Step-by-step instructions for Claude to follow: 1. **Step One**: What to do first 2. **Step Two**: What to do next 3. **Step Three**: How to complete the task ## Error Handling What to do when things go wrong. ## Important Notes - Edge cases to watch for - Constraints and limitations ``` ### Skill Best Practices - **Description is critical**: Claude uses it to decide when to invoke the skill. Include action verbs and user intent phrases. - **Be specific in steps**: Write instructions as if for another agent that has no prior context. - **Include error handling**: Every skill should cover failure modes. - **Keep focused**: One skill = one capability. Split complex workflows into separate skills. - **User-invocable skills** appear as `/plugin-name:skill-name` slash commands. ## 4. Agents Agents are specialized subagents for complex, multi-step operations. They run autonomously with their own tool access. ### File Structure ``` agents/ └── my-agent.md ``` ### Agent Format ```markdown --- name: my-agent description: >- When Claude should invoke this agent. Include specific examples of user requests that should trigger it. Examples: - "review my code for security issues" - "analyze the test coverage" tools: Glob, Grep, Read, Bash, Write, Edit model: sonnet color: cyan --- You are a [role description]. Your job is to [core mission]. ## Core Process **1. Analysis Phase** What to investigate first and how. **2. Execution Phase** What actions to take based on findings. **3. Output Phase** What to report back and in what format. ## Quality Standards - Standard 1 - Standard 2 ## Constraints - What this agent should NOT do - Boundaries of responsibility ``` ### Agent Frontmatter Fields | Field | Required | Description | |-------|----------|-------------| | `name` | Yes | Unique identifier (kebab-case) | | `description` | Yes | When to invoke + example triggers | | `tools` | No | Comma-separated list of available tools | | `model` | No | `sonnet`, `opus`, `haiku`, or `inherit` | | `color` | No | Terminal output color | ### Agent Best Practices - **Description with examples**: Include 2-3 example user requests that should trigger the agent. - **Available tools**: Only list tools the agent actually needs. Common tools: `Glob`, `Grep`, `Read`, `Write`, `Edit`, `Bash`, `WebFetch`, `WebSearch`, `TodoWrite`. - **Model selection**: Use `sonnet` for most agents (fast, capable). Use `opus` only for complex reasoning tasks. Use `haiku` for simple, high-volume operations. - **System prompt**: Write it as direct instructions. Be specific about process, output format, and constraints. - **Single responsibility**: Each agent handles one domain. Don't make swiss-army-knife agents. ## 5. Hooks Hooks respond to Claude Code events automatically. They run shell commands, LLM prompts, or agentic verifiers. ### Configuration (`hooks/hooks.json`) ```json { "hooks": { "EventName": [ { "matcher": "regex_pattern", "hooks": [ { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/my-script.sh" } ] } ] } } ``` ### Available Events | Event | When it fires | Common uses | |-------|--------------|-------------| | `PreToolUse` | Before a tool runs | Validation, security checks | | `PostToolUse` | After a tool succeeds | Formatting, notifications | | `PostToolUseFailure` | After a tool fails | Error recovery | | `UserPromptSubmit` | User sends a message | Auto-routing, context injection | | `SessionStart` | Session begins | Config verification, setup | | `SessionEnd` | Session ends | Cleanup | | `Stop` | Claude tries to stop | Iteration loops | | `SubagentStart` | Subagent starts | Monitoring | | `SubagentStop` | Subagent stops | Quality gates | | `PreCompact` | Before context compaction | Memory preservation | | `Notification` | Claude sends notification | Alert routing | ### Hook Types **Command hooks** run shell scripts: ```json { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/check.sh" } ``` **Prompt hooks** evaluate with an LLM: ```json { "type": "prompt", "prompt": "Check if $ARGUMENTS contains security vulnerabilities. If yes, respond with BLOCK and explanation." } ``` **Agent hooks** run agentic verifiers with tool access: ```json { "type": "agent", "prompt": "Verify that the code changes follow project conventions using $ARGUMENTS as context." } ``` ### Hook Script Requirements 1. Must be executable: `chmod +x hooks/my-script.sh` 2. Must have a shebang: `#!/usr/bin/env bash` 3. Must use `${CLAUDE_PLUGIN_ROOT}` for all paths (never hardcode absolute paths) 4. Receives event data as JSON on stdin 5. Exit codes: `0` = success, `2` = block the action (for Pre* hooks) ### Hook Script Template ```bash #!/usr/bin/env bash set -euo pipefail # Read event data from stdin INPUT=$(cat) # Extract fields (example for PostToolUse) TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null || echo "") # Your logic here if [ "$TOOL_NAME" = "Write" ]; then echo "File written successfully" fi exit 0 ``` ## 6. MCP Server Integration For plugins that need custom tools, register MCP servers in `.mcp.json` at the plugin root. ```json { "mcpServers": { "my-server": { "type": "stdio", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/mcp-server/dist/index.cjs"], "env": { "API_KEY": "${MY_API_KEY}" } } } } ``` Always use `${CLAUDE_PLUGIN_ROOT}` for paths. MCP servers start automatically when the plugin loads. ## 7. Commands (Legacy) Commands are simpler than skills — single markdown files in `commands/`. For new development, prefer skills unless you need a simple, single-file slash command. ```markdown --- name: my-command description: What this command does args: "[optional-arg]" --- Instructions for Claude when this command is invoked. The user said: $ARGUMENTS ``` --- ## Development Workflow ### Creating a New Plugin 1. Create directory at repo root: `mkdir my-plugin` 2. Create manifest: `my-plugin/.claude-plugin/plugin.json` 3. Add components in default locations (`skills/`, `agents/`, `hooks/`, etc.) 4. Test locally: `claude --plugin-dir ./my-plugin` 5. Validate: Use `/plugin validate` inside Claude Code 6. Add to `marketplace.json` for local marketplace testing 7. Write `README.md` with setup instructions ### Testing Locally ```bash # Run Claude with your plugin loaded claude --plugin-dir ./my-plugin # Debug plugin loading claude --debug --plugin-dir ./my-plugin # Validate plugin structure # (inside Claude Code session) /plugin validate ``` ### Adding to Local Marketplace Add an entry to `marketplace.json`: ```json { "name": "my-plugin", "source": "./my-plugin", "description": "What this plugin does", "version": "1.0.0", "author": { "name": "betojuareziii" } } ``` --- ## Patterns From This Repo ### Persistent Storage Pattern Store plugin data in `.claude-plugin/` as JSON files: ``` .claude-plugin/ ├── plugin.json └── data.json # Plugin-specific persistent data ``` ### Interactive UI Pattern (bulk-messenger-minimal) For browser-based interactions: 1. Python HTTP server in `scripts/` serves HTML from `templates/` 2. Hook detects user intent and starts the server 3. Agent manages the workflow (start server → open browser → wait → process result) 4. Result saved to persistent storage ### MCP Server Pattern (notion-crm-plugin) For rich tool integrations: 1. TypeScript source in `mcp-server/src/` 2. Compiled output in `mcp-server/dist/` 3. Registered in `.mcp.json` at plugin root 4. Tools organized by domain in `mcp-server/src/tools/` --- ## Common Mistakes to Avoid 1. **Putting components inside `.claude-plugin/`** — Only `plugin.json` goes there 2. **Hardcoding absolute paths in hooks** — Always use `${CLAUDE_PLUGIN_ROOT}` 3. **Forgetting `chmod +x` on hook scripts** — Scripts must be executable 4. **Writing skills as code** — Skills are markdown instructions, not executable code 5. **Overly broad agent descriptions** — Be specific about when to invoke 6. **Missing error handling in skills** — Always cover failure modes 7. **Using absolute paths in manifest** — All paths must be relative with `./` prefix 8. **Swiss-army-knife agents** — One agent = one domain of responsibility 9. **Skipping validation** — Always run `/plugin validate` before publishing 10. **No README** — Every plugin needs setup and usage documentation ## Environment Variables | Variable | Purpose | |----------|---------| | `CLAUDE_PLUGIN_ROOT` | Absolute path to plugin directory (use in hooks, MCP, scripts) | ## File Naming Conventions | Component | Naming | Example | |-----------|--------|---------| | Plugin directory | kebab-case | `my-plugin/` | | Skill directory | kebab-case | `skills/code-review/` | | Skill file | Always `SKILL.md` | `skills/code-review/SKILL.md` | | Agent file | kebab-case `.md` | `agents/code-reviewer.md` | | Command file | kebab-case `.md` | `commands/deploy.md` | | Hook config | Always `hooks.json` | `hooks/hooks.json` | | Hook scripts | kebab-case | `hooks/check-security.sh` | | MCP config | Always `.mcp.json` | `.mcp.json` | | LSP config | Always `.lsp.json` | `.lsp.json` |