developing-claude-code-plugins

Files (5)

• SKILL.md
• common-patterns.md · references/
• plugin-structure.md · references/
• polyglot-hooks.md · references/
• troubleshooting.md · references/

SKILL.md (first lines)

# Developing Claude Code Plugins

## Overview

This skill provides efficient workflows for creating Claude Code plugins. Use it to make plugin development fast and correct - it synthesizes official docs into actionable steps and provides working examples.

## When to Use

Use this skill when:
- Creating a new Claude Code plugin from scratch
- Adding components to an existing plugin (skills, commands, hooks, MCP servers)
- Setting up a development marketplace for testing
- Troubleshooting plugin structure issues
- Understanding plugin architecture and patterns
- Releasing a plugin (versioning, tagging, marketplace distribution)
- Publishing updates or maintaining existing plugins

**For comprehensive official documentation**, use the `working-with-claude-code` skill to access full docs.

## Quick Reference

| Need to... | Read This | Official Docs |
|-----------|-----------|---------------|
| Understand directory structure | `references/plugin-structure.md` | `plugins.md` |
| Choose a plugin pattern | `references/common-patterns.md` | `plugins.md` |
| Make hooks work cross-platform | `references/polyglot-hooks.md` | `hooks.md` |
| Debug plugin issues | `references/troubleshooting.md` | Various |
| See working examples | `examples/` directory | N/A |

## Plugin Development Workflow

### Phase 1: Plan

Before writing code:

1. **Define your plugin's purpose**
   - What problem does it solve?
   - Who will use it?
   - What components will it need?

2. **Choose your pattern** (read `references/common-patterns.md`)
   - Simple plugin with one skill?
   - MCP integration with guidance?
   - Command collection?
   - Full-featured platform?

3. **Review examples**
   - `examples/simple-greeter-plugin/` - Minimal plugin
   - `examples/full-featured-plugin/` - All components
   - Installed plugins in `~/.claude/plugins/`

### Phase 2: Create Structure

1. **Create directories** (see `references/plugin-structure.md` for details):
   ```bash
   mkdir -p my-plugin/.claude-plugin
   mkdir -p my-plugin/skills
   # Add other component directories as needed
   ```

2. **Write plugin.json** (required):
   ```json
   {
     "name": "my-plugin",
     "version": "1.0.0",
     "description": "What your plugin does",
     "author": {"name": "Your Name"}
   }
   ```
   See `references/plugin-structure.md` for complete format.

3. **Start Claude Code with your plugin loaded** (no install step needed):

   ```bash
   claude --plugin-dir ./my-plugin
   ```

   See `references/plugin-structure.md` for `--plugin-dir` details and the marketplace.json format (used for distribution, not local dev).

### Phase 3: Add Components

Use TodoWrite to track component creation:

**Example:**
```
- Create skill: main-workflow
- Add command: /hello
- Configure hooks
- Write README
- Test installation
```

For each component type, see:
- **Format/syntax**: `references/plugin-structure.md`
- **When to use**: `references/common-patterns.md`
- **Working code**: `examples/` directory

### Phase 4: Test Locally

1. **Load for testing** (no install step):

   ```bash
   claude --plugin-dir ./my-plugin
   ```

2. **Test each component**:
   - Skills: Ask for tasks matching skill descriptions
   - Commands: Run `/your-command`
   - MCP servers: Check tools are available
   - Hooks: Trigger relevant events

3. **Iterate** — after changes run `/reload-plugins` to pick them up mid-session. For MCP/LSP server changes, a full restart is required.

### Phase 5: Debug and Refine

**Start here:** run `claude plugin validate` (or `/plugin validate` in-session) to catch structural errors immediately.

If something doesn't work, read `references/troubleshooting.md` for:
- Plugin not loading

From joeblackwaslike/agent-skills, MIT.

More from joeblackwaslike/agent-skills