02-5 Skills / Hooks / Subagents / Plugins: Mechanism Overview

What this unit solvesThese four mechanisms transform Claude Code from “a conversational agent” into “an automated system that fits your workflow.” They are commonly misused: tasks that require guaranteed behavior are written as Skills and left for the model to remember; subtasks that should be isolated are jammed into the main context; configurations that should be packaged are copied by hand. This unit first gives you the selection criteria for “when to use which one,” then unpacks the format, placement, priority order, and security boundaries for each mechanism individually. Deep production details are left for Part IV — this unit establishes the selection overview.

Learning objectives

Explain what problem each of Skill / Hook / Subagent / Plugin solves, and given a task, determine which one to reach for.
Read and understand the main frontmatter fields of a SKILL.md and a subagent definition.
List the main Hook events and handler types, and describe one practical example of a deterministic gate.
Safely install a plugin from the official and community marketplaces, and know what to scan before installing.

Currency noticeMechanisms and fields were verified as of 2026-05. Claude Code evolves quickly; for exact fields and event lists refer to the official documentation. Production details are in the dedicated Part IV units.

1. Decide first: selecting among the four mechanisms

The four mechanisms are not parallel substitutes — they answer different questions. Read the selection table first, then continue to the per-mechanism details:

What you want	Use	Why
A reusable process — have Claude handle a class of task step by step	Skill	Body loads on demand; at rest it is only one line of description, saving tokens
A deterministically guaranteed action (formatting, blocking dangerous commands)	Hook	Event-driven, enforced by Claude Code itself — not dependent on model compliance
Isolating a subtask into a clean context (exploration, review) — main agent gets only the conclusion	Subagent	Independent context window, saves main-thread tokens and improves quality
Packaging and distributing the above to a team or others	Plugin	One install brings along skills / agents / hooks / MCP together

Selection principle: Use Hook for “must happen,” Skill for “reusable process,” Subagent for “isolated context,” Plugin for “package and distribute.” They are orthogonal but composable — a single plugin can carry a skill, a hook, and a subagent at the same time.

The most common selection mistake: writing Hook-worthy behavior into a Skill or CLAUDE.mdThings like “format after every save” or “block writes to certain paths” need to be guaranteed. Writing them into CLAUDE.md or a Skill is asking the model to comply — and the model may miss it. For something that must happen without fail, use a Hook (see Section 3 and the strategy-vs-rule distinction in 01-6).

Interactive selection tool

Answer a few questions below and get a mechanism recommendation:

2. Skills: reusable processes

A Skill is a reusable process defined in a SKILL.md file (YAML frontmatter + Markdown body). Unlike CLAUDE.md, which is fully loaded at session start, Skills use progressive disclosure: only the description enters context when the session begins; the full SKILL.md body is loaded as a message only when the Skill is triggered [1]. This lets you install dozens of Skills without bloating the context window. Main frontmatter fields (all optional; only description is strongly recommended) [1]:

Field	Purpose
`description`	Purpose and trigger conditions; Claude uses this to decide whether to auto-load the Skill (combined with `when_to_use`, 1536-character limit)
`allowed-tools` / `disallowed-tools`	Tools added to / removed from the allowed set while this Skill is active, without prompting
`model` / `effort`	Override the model or effort level while this Skill is active; restored when the turn ends
`disable-model-invocation`	If `true`, Claude will not auto-load the Skill and the description does not enter context; only manual `/name` invocation works
`user-invocable`	If `false`, the Skill does not appear in the `/` menu, but Claude can still auto-load it
`context: fork` + `agent`	Run inside a forked subagent; `agent` specifies the subagent type
`paths`	Glob pattern; only auto-triggers when the operation touches a matching file path

A minimal SKILL.md

---
name: tidy-refs
description: Clean up a reference list in the lab's citation format. Trigger when the user asks to organize references or BibTeX entries.
allowed-tools: Read, Edit
---

# Tidy references
1. Read the reference file the user specifies.
2. Reorder entries in IEEE numbering; use et al. for three or more authors.
3. Mark entries missing a year with n.d. (no date) -- do not invent dates.

Place it at ~/.claude/skills/tidy-refs/SKILL.md (personal) or .claude/skills/tidy-refs/SKILL.md (project). Claude only reads these instructions after the Skill is triggered.

Placement and priority (highest to lowest): enterprise managed policy > personal ~/.claude/skills/ > project .claude/skills/ > plugin (plugin skills use the plugin-name:skill-name namespace and do not conflict with other layers) [1]. Dynamic context injection: SKILL.md can contain commands that execute before the Skill loads and whose output replaces the command inline — letting you inject live information (git status, date) into the process [1]. The syntax is a leading backtick-escaped command on its own line; multi-line blocks are also supported:

!`git status --short`

You can disable this behavior with disableSkillShellExecution: true in settings.json. Relationship with legacy commands: .claude/commands/<name>.md is still supported and generates the same /name slash command. When a Skill and a command share the same name, the Skill wins [1]. For the trade-offs between Commands and Skills see 04-3 and 04-4.

3. Hooks: deterministic event-driven gates

A Hook is a custom command attached to a lifecycle event. The fundamental difference between Hooks and Skills / CLAUDE.md is enforceability: CLAUDE.md says “please follow this,” and a Hook says “I will make sure this happens.” Use Hooks for anything that must be guaranteed; do not write it into instructions and hope for model compliance. Events: Claude Code had approximately 30 hook events as of 2026-06 [2]. The ones you will reach for first:

Event	When it fires	Typical use
`SessionStart`	Session begins	Inject project context, environment check
`UserPromptSubmit`	After you submit a prompt	Inject dynamic context, intercept
`PreToolUse`	Before a tool executes	Block dangerous commands, rewrite parameters
`PostToolUse`	After a tool executes	Auto-format / lint / type-check
`Stop`	Turn ends	Deterministic wrap-up verification (convergence sentinel)
`SessionEnd`	Session ends	Cleanup, final validation

The full event list (including PermissionRequest, SubagentStart / SubagentStop, PreCompact, and others) is in the official docs and 04-6. Handler types: command (run a shell command or script), http (POST event JSON to a URL), mcp_tool (call an MCP tool), prompt (evaluate with an LLM), agent (agentic verifier with tools) [2]. Protocol: a Hook receives a JSON payload via stdin (containing session_id, tool_name, tool_input, and more). Exit code 2 is a blocking error (stderr is shown to Claude and the action is blocked); exit 0 triggers parsing of the stdout JSON for a decision [2]. To block a specific tool call in PreToolUse, return:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes not allowed"
  }
}

A PostToolUse hook that auto-formats on saveAttach a PostToolUse hook in settings.json pointing to a script, with matcher Edit|Write:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": ".claude/hooks/format.sh" }]
      }
    ]
  }
}

The hook script reads the modified file path from the stdin JSON (tool_input.file_path) and runs the formatter against it. Note that Claude Code does not provide a $CLAUDE_FILE_PATHS environment variable for this (as of 2026-05) [2] — the path must come from stdin JSON, not from the environment.

4. Subagents: child agents with isolated context

A Subagent is a child agent defined in .claude/agents/*.md (YAML frontmatter + system prompt) and managed via /agents. Its core value is context isolation: dispatch an exploration-heavy or read-heavy subtask to a subagent with a clean context window, and the main agent receives only the final conclusion — saving main-thread tokens and preventing irrelevant content from diluting the main context (connects to 01-4) [3]. Main frontmatter fields (only name and description are required) [3]:

Field	Purpose
`name` / `description`	Identifier and the basis for “when to delegate”
`tools` / `disallowedTools`	Tool allowlist / blocklist; omitting `tools` inherits all tools from the parent conversation
`model`	`sonnet` / `opus` / `haiku` / full model ID / `inherit` (default: inherit)
`skills`	List of Skills whose full content is injected directly at startup
`memory`	`user` / `project` / `local`, each corresponding to a different agent-memory directory
`isolation`	The only valid value is `worktree`, which runs the subagent in a temporary git worktree

Placement and priority (highest to lowest): managed policy > --agents CLI flag > project .claude/agents/ > user ~/.claude/agents/ > plugin [3]. Built-in subagents: Explore (Haiku, read-only, skips CLAUDE.md, for search and analysis), Plan (read-only planning), general-purpose (full tools, complex multi-step tasks) [3]. One important constraint: subagents cannot generate subagents (no nested delegation).

A read-only review subagent

---
name: kb-reviewer
description: Review knowledge-base units for compliance with the writing spec. Use before marking a unit complete.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a read-only quality reviewer. Check tone, full-width punctuation, dead links, and
currency annotations against writing-spec.md. Return a tiered issue list. Do not modify any files.

Giving it only read-only tools is least-privilege in practice. The main agent delegates and receives only the issue list — it never has the review process’s extensive file reads diluting its own context. For full subagent production details see 04-5.

5. Plugins and marketplaces: packaging and distribution

A Plugin packages skills, agents, hooks, and MCP servers into a single installable unit, letting a team install a consistent configuration in one step. Marketplaces and installation (as of 2026-05) [4]:

Official marketplace claude-plugins-official is available automatically on startup: /plugin install <name>@claude-plugins-official, browsable at claude.com/plugins.
Community marketplace anthropics/claude-plugins-community: first run /plugin marketplace add anthropics/claude-plugins-community, then /plugin install <name>@claude-community.
Arbitrary marketplace: /plugin marketplace add owner/repo (GitHub), a Git URL, or a local path (the repo must contain .claude-plugin/marketplace.json).

Plugin structure: .claude-plugin/plugin.json at the repo root is the manifest (the only file in that directory). Components go in the outer skills/, agents/, commands/, hooks/hooks.json, .mcp.json, .lsp.json, monitors/monitors.json, and bin/, plus a plugin-level settings.json (only agent and subagentStatusLine keys take effect) [4]. The official documentation explicitly warns: do not put commands/, agents/, skills/, or hooks/ inside the .claude-plugin/ directory — only plugin.json goes there. Full directory layout:

my-plugin/

.claude-plugin/

plugin.json · the only file that belongs here

skills/

agents/

hooks/

commands/

.mcp.json

settings.json · only agent / subagentStatusLine keys take effect

Scan before installing: plugins and Skills are supply-chain assetsA community Skill or plugin is someone else’s code and instructions running inside your agent. Before installing, scan for: hidden Unicode (prompt injection), outbound-execute patterns like curl | bash, overly broad tool permissions, ANTHROPIC_BASE_URL overrides, and enableAllProjectMcpServers auto-approval. High star counts do not mean safe or maintained. For the full threat model, scan commands, and relevant CVEs see 03-3; for correct usage see 04-7.

Tool comparison

Mapping the four mechanisms across tools reveals uneven coverage (as of 2026-05; exact mechanisms are subject to each vendor’s current documentation; see 02-6 for deeper comparison):

Concept	Anthropic Claude (primary)	OpenAI (Codex)	Google (Gemini CLI)	GitHub Copilot	Cursor
Reusable process (Skill / command)	`SKILL.md` + `.claude/commands/` [1]	prompts / custom instructions (per official docs)	custom instructions (per official docs)	`.prompt.md` (per official docs)	`.cursor/rules/*.mdc`
Event-driven Hook	`hooks` events (~30 events) [2]	per official docs	per official docs	per official docs	no equivalent Hook mechanism
Subagent / context isolation	`.claude/agents/*.md` + built-in Explore / Plan [3]	per official docs	per official docs	per official docs	per official docs
Plugin / extension marketplace	plugin + marketplace [4]	per official docs	extensions (per official docs)	per official docs	per official docs

The comparison table gives coordinates onlyNaming and maturity of mechanisms varies significantly across vendors; precise details are subject to each vendor’s current official documentation. Claude Code provides approximately 30 hook events and built-in subagent context isolation [2, 3]; most other tools lean toward “instructions / rules” layers without an equivalent deterministic event mechanism. For deeper comparison see 02-6.

Hands-on exercises

Write a minimal Skill

Following the example in Section 2, create a SKILL.md under ~/.claude/skills/ (for example, “clean up references in the lab’s citation format”) with only a description and the procedure steps. Trigger it and confirm that Claude actually follows the steps.

Add a PostToolUse Hook to run lint / formatting after every save

Following the example in Section 3, attach a PostToolUse hook in settings.json with an Edit|Write matcher, pointing to a script that reads tool_input.file_path from the stdin JSON. Edit a file and confirm the hook actually fires.

Build a read-only review subagent

Following the example in Section 4, create a subagent in .claude/agents/ that is given only Read / Grep tools. Use /agents to confirm it loads, then dispatch it to review some content and receive only the conclusion.

Common pitfalls

Anti-pattern list

Writing Hook-worthy behavior into CLAUDE.md and hoping for compliance: formatting and blocking dangerous commands must be guaranteed. CLAUDE.md and Skills both rely on model compliance, which can be missed. Use a Hook.
Installing high-star but unmaintained or overly permissive plugins: stars reflect marketing reach, not safety or maintenance. Scan before installing (see 03-3).
Giving a subagent too many tool permissions: a review-only subagent with write tools violates least privilege. Read-only tasks get read-only tools.
Using a Skill for an exploration task that should be isolated: dumping large amounts of reads into the main context dilutes it. Use a subagent, send only the conclusion.
Placing components inside .claude-plugin/: only plugin.json belongs there. skills/, agents/, and hooks/ go in the outer directory [4].

Self-check

The bar for passing this unit

Given a recurring task (for example, “run tests before every commit and block failing commits”), can you determine whether to use a Skill, a Hook, or a Subagent? What is your reasoning?
What is the difference in effect between disable-model-invocation: true and user-invocable: false on a Skill?
If you want Claude Code to always run formatting after every save, which hook event do you use? Why not put this in CLAUDE.md?
What tool permissions should a review-only subagent have? What principle does giving it write tools violate?
Before installing a plugin from the community marketplace, what categories of risk signals do you scan for?

Sources and further reading

Factual claims are grounded in official documentation; fast-changing items are annotated as of 2026-05.

[1] Anthropic, “Skills,” Claude Code Docs. (SKILL.md frontmatter fields; progressive disclosure — loads on demand; placement priority: enterprise > personal > project > plugin; !`command` dynamic injection and disableSkillShellExecution; Skill wins over a same-named .claude/commands/ entry) https://code.claude.com/docs/en/skills (as of 2026-05)
[2] Anthropic, “Hooks,” Claude Code Docs. (~30 hook events; handler types: command / http / mcp_tool / prompt / agent; stdin JSON protocol, exit code 2 blocks, exit 0 + JSON decision; PreToolUse permissionDecision: deny; matcher syntax; no $CLAUDE_FILE_PATHS environment variable — path comes from stdin JSON tool_input.file_path) https://code.claude.com/docs/en/hooks (as of 2026-05)
[3] Anthropic, “Subagents,” Claude Code Docs. (.claude/agents/*.md frontmatter; placement priority: managed > --agents > project > user > plugin; built-in Explore / Plan / general-purpose; context isolation returns only the conclusion; subagents cannot be nested; isolation: worktree) https://code.claude.com/docs/en/sub-agents (as of 2026-05)
[4] Anthropic, “Plugins,” Claude Code Docs. (official marketplace claude-plugins-official available automatically; community anthropics/claude-plugins-community; /plugin install, /plugin marketplace add; plugin structure: .claude-plugin/plugin.json + outer skills/ agents/ hooks/hooks.json .mcp.json; only plugin.json goes in .claude-plugin/) https://code.claude.com/docs/en/plugins (as of 2026-05)

Related: 01-6 on the strategy-vs-rule distinction (the design starting point for Hooks); 04-3 Command; 04-4 Skill; 04-5 Subagent; 04-6 Hooks; 04-7 Plugin production details; 03-3 security and supply-chain threat model.

Overview

Part I Foundations

Part II Configuration

Part III Judgment

Part IV Customization

Part V Case Studies

Appendix

02-5 Skills / Hooks / Subagents / Plugins: Mechanism Overview

Learning objectives

1. Decide first: selecting among the four mechanisms

Interactive selection tool

2. Skills: reusable processes

3. Hooks: deterministic event-driven gates

4. Subagents: child agents with isolated context

5. Plugins and marketplaces: packaging and distribution

Tool comparison

Hands-on exercises

Common pitfalls

Self-check

Sources and further reading

​Learning objectives

​1. Decide first: selecting among the four mechanisms

​Interactive selection tool

​2. Skills: reusable processes

​3. Hooks: deterministic event-driven gates

​4. Subagents: child agents with isolated context

​5. Plugins and marketplaces: packaging and distribution

​Tool comparison

​Hands-on exercises

​Common pitfalls

​Self-check

​Sources and further reading

Learning objectives

1. Decide first: selecting among the four mechanisms

Interactive selection tool

2. Skills: reusable processes

3. Hooks: deterministic event-driven gates

4. Subagents: child agents with isolated context

5. Plugins and marketplaces: packaging and distribution

Tool comparison

Hands-on exercises

Common pitfalls

Self-check

Sources and further reading