my-plugin/
├── .claude-plugin/
│   └── plugin.json         # Plugin metadata
├── skills/
│   └── skill-name/
│       ├── SKILL.md        # Required
│       ├── references/     # Detailed docs
│       ├── examples/       # Working code
│       └── scripts/        # Utilities
├── commands/
│   └── command-name.md
├── agents/
│   └── agent-name.md
└── hooks/
    └── hooks.json

---
name: skill-name
description: This skill should be used when the user asks to "specific phrase 1", "specific phrase 2", or mentions "keyword". Be specific about triggers.
version: 1.0.0
---

# Skill Title

Core content here (1,500-2,000 words ideal).

## Additional Resources

- **`references/detailed.md`** - Detailed patterns
- **`examples/working.sh`** - Working example

description: This skill should be used when the user asks to "create a hook", "add PreToolUse hook", "validate tool use", or mentions hook events.

description: Provides hook guidance.  # Too vague
description: Use this skill for hooks.  # Not third person

# Good
Start by reading the configuration.
Validate the input before processing.

# Bad
You should start by reading...
You need to validate the input...

---
name: command-name
description: What the command does
argument-hint: "[optional args]"
---

# Command Title

Instructions for executing the command.

---
name: review-pr
description: Review a GitHub PR with detailed code analysis
argument-hint: "[PR number or URL]"
---

# Review PR Command

1. Fetch PR details using `gh pr view`
2. Get changed files with `gh pr diff`
3. Analyze each file for issues
4. Provide summary with recommendations

---
agent: agent-name
description: |
  When to use this agent with examples:
  <example>
  Context: User situation
  user: "User request"
  assistant: "How assistant responds"
  <commentary>Why this agent is appropriate</commentary>
  </example>
model: sonnet
tools:
  - Read
  - Glob
  - Grep
  - Bash
color: cyan
---

# Agent Instructions

Detailed instructions for the agent's behavior.

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "Write|Edit",
      "type": "prompt",
      "prompt": "Validate code before writing...",
      "timeout": 10000
    }
  ]
}