# plugin-mastery

> Claude Code plugin architecture, structure, and best practices.
Use when creating plugins, skills, commands, hooks, or agents.
Covers frontmatter validation, naming conventions, and patterns.

- Author: Colin Neller
- Repository: cneller/van-claude
- Version: 20260125190645
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/cneller/van-claude
- Web: https://mule.run/skillshub/@@cneller/van-claude~plugin-mastery:20260125190645

---

# Plugin Mastery Skill

```yaml
name: plugin-mastery
description: |
  Claude Code plugin architecture, structure, and best practices.
  Use when creating plugins, skills, commands, hooks, or agents.
  Covers frontmatter validation, naming conventions, and patterns.
```

## Quick Reference

### Skill Frontmatter Rules

| Field         | Constraint                                    | Example                     |
|---------------|-----------------------------------------------|-----------------------------|
| `name`        | ≤64 chars, `[a-z0-9-]`, no "anthropic/claude" | `processing-pdfs`           |
| `description` | ≤1024 chars, third person, include "when"     | "Process PDFs. Use when..." |

### Structure Limits

| Element    | Limit                       |
|------------|-----------------------------|
| Body       | ≤500 lines                  |
| References | Max 1 level deep            |
| TOC        | Required if body >100 lines |

### Naming Conventions

| Pattern       | Example           | Use For                |
|---------------|-------------------|------------------------|
| Gerund form   | `processing-pdfs` | Action-oriented skills |
| Noun form     | `pdf-processor`   | Tool-oriented skills   |
| Workflow form | `pdf-to-markdown` | Conversion workflows   |

### Hook Types

| Hook         | When                      | Use Case              |
|--------------|---------------------------|-----------------------|
| SessionStart | Conversation begins       | Environment setup     |
| PreToolUse   | Before tool execution     | Validation, blocking  |
| PostToolUse  | After tool execution      | Logging, modification |
| Stop         | Before response completes | Final checks, cleanup |
| Notification | Background task completes | User alerts           |

### Plugin Structure

```text
plugin-name/
├── plugin.json           # Required: metadata
├── CLAUDE.md             # Plugin-wide instructions
├── skills/
│   └── skill-name/
│       ├── SKILL.md      # Skill definition
│       └── reference/    # Supporting docs (1 level max)
├── commands/
│   └── command.md        # Slash commands
├── agents/
│   └── agent.md          # Subagent definitions
└── hooks/
    └── hook-name.md      # Hook definitions (or .sh/.py)
```

## Reference Documents

- [Skill Best Practices](./reference/skill-best-practices.md) - Naming, descriptions, content principles
- [Hook Patterns](./reference/hook-patterns.md) - Hook types, matchers, security
- [Plugin Structure](./reference/plugin-structure.md) - Directory layout, plugin.json fields
- [Frontmatter Validation](./reference/frontmatter-validation.md) - Rules, examples, common mistakes

## When to Use This Skill

- Creating new Claude Code plugins
- Writing skills, commands, or agents
- Implementing hooks for tool validation
- Debugging plugin loading issues
- Reviewing plugin architecture decisions