developing-claude-plugins

What this skill does

# Claude Code Plugin & Marketplace Expert

You are an expert in developing Claude Code marketplaces and plugins. This skill ensures that all elements in this package follow current best practices, maintain consistency, and are optimally structured.

## When This Skill Activates

**File patterns that trigger this skill:**
- `plugins/**/*` - Any file in the plugins directory
- `**/SKILL.md` - Skill definition files
- `**/commands/**/*.md` - Command files
- `**/agents/**/*.md` - Agent files
- `**/hooks/**/*` - Hook configurations and scripts
- `marketplace.json` - Marketplace definition
- `plugin.json` - Plugin manifests

## Gotchas

- **`argument-hint` with `[...]` brackets MUST be quoted** — `argument-hint: [branch-name]` is parsed by YAML as a list (`["branch-name"]`) and breaks the command silently. Always write `argument-hint: "[branch-name]"`. This is the #1 cause of broken commands across the marketplace.
- **`description` with embedded `"..."` MUST use single-quote wrapping** — `description: 'Activates when user says "rebase"'` works. `description: "Activates when user says "rebase""` is invalid YAML. Always verify with `claude plugin validate <plugin-dir>`.
- **Plugin-agent frontmatter ignores `permissionMode`, `mcpServers`, and `hooks`** — Security restriction since docs 2.1.78+. Setting them looks valid but silently has no effect. Plugin-agents needing MCP must add a body note that MCP must be configured in the user's session.
- **Hard-coded `model:` and `effort:` on agents DEGRADES the user's setup** — If developers run with Opus 4.7 + `effort: high`, an agent with `model: sonnet, effort: medium` runs SLOWER and WORSE than the user's default. Use `model: inherit` + no `effort` field (inherit) unless explicitly upgrading (`effort: max` for security/review-critical agents).
- **`Agent` tool does NOT work in subagents** — Listing `Agent` in a subagent's `tools:` is silently ignored. Subagents cannot spawn sub-subagents. For parallel work inside an agent, use `isolation: worktree` instead.
- **`Skill` and `LSP` are NOT valid Claude Code tools** — Listing them in `tools:` causes frontmatter validation to fail. Skills load via `skills:` frontmatter, LSP runs implicitly.
- **`permissions.json` `usedBy` arrays drift silently** — When you rename an agent or skill, the `usedBy` references in `permissions.json` don't auto-update. Run `grep -r "old-name" plugins/*/permissions.json` before finalizing a rename.
- **Skills storing state in their own directory lose data on plugin update** — Skill directories are recreated on update. For persistent state use `${CLAUDE_PLUGIN_DATA}` (since 2.1.78), not the skill directory itself.

**Actions that trigger this skill:**
- Creating new plugins, agents, commands, hooks, skills, or scripts
- Modifying existing plugin elements
- Reviewing or optimizing plugin structure
- Discussing Claude Code extension development

## Mandatory Pre-Work: Documentation Review

**CRITICAL:** Before ANY implementation or optimization, fetch the latest official documentation.

### Primary Sources (GitHub - always available)

Fetch these GitHub sources first:
```
WebFetch: https://github.com/anthropics/claude-code/blob/main/plugins/README.md
WebFetch: https://github.com/anthropics/skills/blob/main/README.md
```

### Secondary Sources (WebSearch)

For specific topics, use targeted searches:
```
WebSearch: "Claude Code [topic] documentation site:claude.com"
```

Topics to search when relevant:
- Plugins & plugin.json structure
- Skills & SKILL.md frontmatter
- Slash commands & command frontmatter
- Subagents & agent configuration
- Hooks & hooks.json structure

Apply the patterns and requirements from these sources.

---

## Element Types Reference

### Skills
**Purpose:** Provide contextual expertise that enhances Claude's capabilities in specific domains.

**Structure:**
```
skills/
└── skill-name/
    ├── SKILL.md           # Main skill definition (REQUIRED)
    ├── reference.md       # Detailed reference documentation
    ├── examples.md        # Usage examples
    └── [topic].md         # Additional topic-specific files
```

**SKILL.md Template:**
```yaml
---
name: skill-name-kebab-case
description: Concise description (max 1024 chars, ideal 500-700). Formula: [What it does] + [When to use it] + [Key capabilities]. Must trigger auto-detection correctly.
---

# Skill Title

[Introductory paragraph explaining the skill's purpose]

## When to Use This Skill

- [Trigger condition 1]
- [Trigger condition 2]

## Core Capabilities

[Main content organized by capability]

## Related Skills

- `related-skill-1` - [relationship]
- `related-skill-2` - [relationship]
```

**Key Principles:**
- Description must answer "WHEN should Claude use this skill?"
- Avoid overlap with other skills
- Include clear boundary definitions
- Reference related skills explicitly

---

### Commands
**Purpose:** User-triggered actions invoked via `/command-name`.

**Structure:**
```
commands/
├── simple-command.md
└── category/
    ├── sub-command-1.md
    └── sub-command-2.md
```

**Template:**
```yaml
---
description: What this command does (shown in /help and command list)
argument-hint: "[optional-args]"   # Optional: shown in autocomplete (MUST quote if value contains brackets)
allowed-tools: Read, Grep, Bash   # Optional: restrict tool access
model: claude-3-5-sonnet-20241022 # Optional: force specific model
---

# Command Title

[Brief description of what this command accomplishes]

## When to Use This Command

- [Use case 1]
- [Use case 2]

## Workflow

### Step 1: [Action]
[Instructions]

### Step 2: [Action]
[Instructions]

## Examples

[Practical examples of command usage]
```

**Naming:** Use kebab-case, e.g., `create-story.md`, `git/commit-message.md`

---

### Agents
**Purpose:** Autonomous agents that handle complex, multi-step tasks with specific tool access.

**File:** `agents/agent-name.md`

**Template:**
```yaml
---
name: agent-name
description: When to use this agent and what tasks it handles autonomously
model: sonnet | opus | haiku
tools: Bash, Read, Grep, Glob, Write, Edit
permissionMode: default | bypassPermissions
skills: optional-comma-separated-skills
---

[Agent persona and mission]

## Use Cases

- [When to spawn this agent]
- [Specific task types it handles]

## Execution Protocol

[Detailed workflow and phases]

## Output Format

[Expected output structure]
```

**Key Principles:**
- Define clear tool restrictions
- Specify appropriate model (haiku for simple, sonnet for complex, opus for critical)
- Include self-verification checklists

---

### Hooks
**Purpose:** Automated responses to Claude Code events.

**Structure:**
```
hooks/
├── hooks.json    # Hook definitions
└── scripts/      # Hook handler scripts
    └── handler.ts
```

**hooks.json Template:**
```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/script.sh"
          }
        ]
      }
    ]
  }
}
```

**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `matcher` | string | Tool filter: `"Write"`, `"Write\|Edit"`, `"Bash(npm test*)"`, or omit for all |
| `type` | string | `"command"` (shell) or `"prompt"` (Claude evaluation) |
| `command` | string | Shell command (for type="command") |
| `timeout` | number | Seconds before timeout (default: 60, optional) |

**Events:**
- `PreToolUse` - Before a tool executes
- `PostToolUse` - After a tool executes
- `PermissionRequest` - When permission is requested
- `UserPromptSubmit` - When user submits a prompt
- `SessionStart` - Session initialization
- `SessionEnd` - Session teardown
- `Stop` - When main agent finishes
- `SubagentStart` - When subagent starts
- `SubagentStop` - When subagent finishes
- `TeammateIdle` - Agent Teams: teammate waiting for work
- `TaskCompleted` - Agent Teams: task finished
- `PreCompact` - Before context compaction

---

## Quality Checklist

### Befo