Skills vs. tools vs. hooks vs. subagents vs. prompts: when to use what

Modern agentic coding tools (Claude Code, OpenAI’s Codex, Gemini CLI, GitHub Copilot, Cursor and many more) have converged on the same handful of ways to customize behavior. Two of them are now shared formats rather than one product’s features: AGENTS.md for project instructions (an Agentic AI Foundation project) and SKILL.md for skills (the open Agent Skills format, which Anthropic created and dozens of tools now read). The mechanisms overlap enough to confuse and differ enough that the wrong pick costs you context, money, or reliability. Here’s the sorting logic, with Claude Code’s details as the worked example (checked against its docs on 2026-10-08).

The five mechanisms in one table

Mechanism	Lives where (Claude Code)	Triggered by	Costs context?
Instructions file (CLAUDE.md / AGENTS.md)	Repo root	Every session, always	Always: keep it lean
Skill (SKILL.md, also your slash commands)	.claude/skills/<name>/	Model decides it’s relevant, or you type /<name>	Description always (one line); body only when loaded
MCP tool	A server you run or install	Model calls it	Names only with tool search (the default); full schema once used
Hook	.claude/settings.json	An event, deterministically	No: runs outside the model
Subagent	.claude/agents/<name>.md	Model (or you) delegates	Isolated: its own window

There used to be a sixth row, slash commands. In Claude Code they have been merged into skills: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy. Old command files keep working; new ones should be skills, because a skill can also carry supporting files and be loaded by the model when relevant.

The decision logic

Is it true in every session? → Instructions file. Project facts, commands, conventions, boundaries. The test: would you tell a new teammate this on day one? Then it belongs there — and only such things, because you pay its token cost every single session. Grab the template.

Is it expertise needed only sometimes? → Skill. A how-to the agent should pull in when the situation matches: “how we write migrations,” “how to cut a release,” “our PDF-report styling.” Skills keep the always-loaded footprint at one line of description each, with the full playbook loaded on demand — the difference between a bookshelf and carrying every book. Because SKILL.md is a shared format, a well-written skill also travels between tools; see how to write Agent Skills.

Does it act on the world outside the conversation? → MCP tool. Databases, ticket systems, internal APIs. Tools are also your enforcement point — validation, redaction, audit — which is why wrapping the API properly matters more than wrapping it quickly. The old objection, “every MCP server’s schema sits in context all session”, is mostly gone where the client supports tool search: Claude Code defers MCP tool definitions by default and loads them when needed. The MCP vs. CLI measurements put numbers on it.

Must it happen every time, no judgment involved? → Hook. Format on save, lint before commit, block writes to protected paths. The key insight: a hook is deterministic — the model can forget an instruction, but it cannot skip a hook. Anything you’d phrase as “always/never do X before Y” is a hook wearing an instruction’s clothing. One detail that bites: in Claude Code a command hook blocks an action only when it exits with code 2. Exit 1 is treated as a non-blocking error and the action goes ahead.

Is it a big, noisy, separable chunk of work? → Subagent. Broad codebase searches, independent reviews, parallel explorations. The subagent burns its own context window and returns only conclusions — your main session stays clean. This is the orchestrator pattern applied to your own working session. Whether a whole system should be split into several agents is a separate question: single agent vs. multi-agent.

Is it a workflow you start, the same way each time? → A skill you invoke by name. Reusable parameterized prompts: “prep a release note,” “review this PR against our checklist.” If you’ve typed essentially the same paragraph three times, it’s a skill. Set disable-model-invocation: true in its frontmatter when only you should trigger it (a deploy, say), so the model never runs it on its own.

The failure modes of choosing wrong

• Situational knowledge in the instructions file → every session pays for expertise used in one session in ten; the file bloats until the model starts skimming it.
• A “never do this” rule as an instruction instead of a hook → it holds until one long session where it doesn’t. Determinism is a feature; use it.
• An MCP tool where a hook belongs → you gave the model discretion over something that shouldn’t be discretionary.
• Main-session searches that belong in a subagent → context fills with file dumps and the actual task degrades.

The meta-rule

Instructions and prompts are suggestions the model weighs; hooks and tool-layer validation are guarantees your infrastructure enforces; skills and subagents are economics — they manage the context budget. Classify what you need (suggestion, guarantee, or economics) and the mechanism usually picks itself.

To set all of this up hands-on (an instructions file, a skill, a hook and an MCP server in one session), follow Claude Code from zero.