Plugin Design
A plugin packages Claude Code's existing extension points so a teammate can install one thing and have Claude be measurably better at your team's work. Designing a plugin is choosing the right components for the job — nothing more architectural than that.
The Four Components
Claude Code gives you four ways to extend a session. A plugin is a package that uses one or more of them.
| Component | What it is | Reach for it when |
|---|---|---|
| Skill | A reusable workflow with a description that lets Claude self-trigger it from context | You want Claude to follow a protocol — code review, research, spec writing — without the user remembering a slash command |
| Hook | A shell command Claude Code runs at lifecycle events (SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop) | You want to nudge, validate, or react around tool use — inject context, lint after writes, audit Bash invocations |
| Agent | A subagent with a custom system prompt and a tailored toolset | You want a focused worker — security auditor, architect, researcher — that runs in its own context window |
| Command | A user-typed slash command (/plugin:command) | You want a deliberate user-invoked entry point. Most workflows are better served by skills (which auto-activate) or by exposing a skill as a command |
See Component Model for the full mechanics.
Choosing Between Them
The four components compose freely — most plugins use several. Some quick mappings:
- "I want Claude to remember to check
.agents/steering/at the start of every session" → hook (SessionStart) - "I want a reusable code-review protocol Claude can run on changed files" → skill that surfaces as
/dev:review - "I want a focused worker that only reads code and writes review comments" → agent with a restricted toolset
- "I want a slash command that kicks off a multi-step feature workflow" → skill invoked as a command (skills surface as
/plugin:skillautomatically)
When in doubt: skills are the workhorse. Hooks are for ambient behaviour around tool use. Agents are for isolation. Commands are mostly about giving skills a discoverable entry point.
A Real Example: How dev Composes Components
The dev plugin uses all four:
- Hooks — auto-approve read-only commands at
PreToolUse; nudge skill awareness based on observed tool patterns atPostToolUse; index installed skills atSessionStart. - Skills —
/dev:research,/dev:review,/dev:spawn-team,/dev:team-feature— each defines a protocol Claude runs through. - Agents — seven specialists (architect, engineer, critic, researcher, code-writer, experience-analyst, storyteller) each with their own system prompt; team skills spawn the right specialists for the work.
- Commands — none defined separately; the invocable skills appear as
/dev:<skill>automatically.
The composition is the design: hooks set the stage, skills orchestrate, agents do focused work. None of these capabilities live in Claude Code itself — dev builds them by composing what's already there.
Related
- Component Model — Mechanics of each component
- Skill Activation — How Claude self-triggers skills
- Hooks & Lifecycle — The hook events you can extend from
- agronod/claude-plugins CONTRIBUTING.md — Repo rules for the Agronod marketplace
- 12-Factor Agents — Concept reading for designing reliable LLM agents; the vocabulary plugin authors compose against