CLAUDE.md vs skills vs subagents vs hooks vs MCP vs plugins: which one should you use?

The short version: one sentence per feature

Each extension point solves a different problem. The examples below are the ones Anthropic's features overview uses.

Claude Code also has output styles, code intelligence and dynamic workflows; they are out of scope here. For every file these features use, see AI agent configuration files explained.

• CLAUDE.md: persistent context loaded every conversation, for example "Use pnpm, not npm. Run tests before committing."
• Skill: instructions, knowledge and workflows Claude uses when relevant, for example a /deploy skill that runs your deployment checklist.
• Subagent: an isolated worker that returns a summary, for example a research task that reads many files but reports only the key findings.
• Hook: a script, HTTP request, MCP tool call, prompt or subagent that runs on a lifecycle event, for example ESLint after every file edit.
• MCP: a connection to an external service, for example querying your database or posting to Slack.
• Plugin: the packaging layer that bundles skills, hooks, subagents and MCP servers so you can reuse them across repos or share them through a marketplace.

A decision flow: where should this instruction go?

Ask these questions in order. They follow the trigger table in Anthropic's "Build your setup over time" section.

• 1. Must it happen every time, whatever the model decides? Use a hook or a permissions rule.
• 2. Does Claude need it in every session? Put it in CLAUDE.md or AGENTS.md, and keep it short.
• 3. Only sometimes, or is it a multi-step procedure you keep pasting? Make it a skill.
• 4. Would doing it flood the main conversation with output you won't reference again? Route it through a subagent, optionally preloaded with skills.
• 5. Does it need a system outside the repo, such as a browser tab Claude can't see? Connect an MCP server.
• 6. Does a second repository or a teammate need the same setup? Package it as a plugin, or install shared skills from a registry (see the end of this guide).

Context cost and precedence: why placement matters

Every feature uses some of Claude's context, and when the same name is defined twice, each feature resolves it differently.

CLAUDE.md vs skills

CLAUDE.md is for facts Claude should always know; a skill is for a procedure or reference it needs only sometimes. A 30-line deployment procedure in CLAUDE.md costs context on every request, while the same text as a skill costs only its description until you run it. Path-scoped rules in .claude/rules/ sit in between: they load when Claude works with matching files. The same split applies to AGENTS.md, which Claude Code now reads on its own only when no CLAUDE.md is present (does Claude Code read AGENTS.md?); see AGENTS.md vs SKILL.md and AGENTS.md vs CLAUDE.md vs Cursor rules. Custom commands in .claude/commands/ still work, but commands are now skills.

Skills vs subagents: when to use each, and how they combine

Use a skill when you want to watch and steer each step in your main conversation. Use a subagent for deep searches, log analysis or dependency audits whose intermediate output you won't need again, and for parallel work.

They combine in two ways. First, a subagent's skills: frontmatter preloads the full content of the listed skills at startup; without it, the subagent can still invoke project, user and plugin skills through the Skill tool. Skills with disable-model-invocation: true can't be preloaded. Second, a skill with context: fork and an agent: field runs itself in a new subagent of that type. Despite the name, that subagent does not see your conversation history, so the skill must stand on its own. Every field involved (context, agent, disable-model-invocation and the rest) is in the SKILL.md frontmatter reference.

Cursor keeps subagents in .cursor/agents/ (and also reads .claude/agents/ and .codex/agents/). Codex custom agents are TOML files in .codex/agents/ or ~/.codex/agents/. Both tools also support skills.

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

Skills vs hooks

A hook is deterministic: Claude Code runs it on every matching event. An instruction in a skill or CLAUDE.md is guidance the model may not follow. So "never read or edit .env files" belongs in a PreToolUse hook or a permissions deny rule, not in a skill. A PreToolUse hook that exits with code 2 blocks the tool call and shows its stderr to Claude.

Hooks live in ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, managed settings, a plugin's hooks/hooks.json, or skill and subagent frontmatter. A skill's hooks field registers hooks when the skill is invoked. Hooks from every level merge, and disableAllHooks can't turn off managed hooks.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-env.sh" }
        ]
      }
    ]
  }
}

#!/bin/sh
file=$(jq -r '.tool_input.file_path // empty')
case "$file" in
  *.env|*/.env.*) echo "Blocked: $file is a secrets file" >&2; exit 2 ;;
esac
exit 0

Skills vs MCP

MCP gives Claude capabilities: tools and data from other systems. A skill gives it know-how, including how to use those tools well. A common pattern is an MCP server for your database plus a skill that documents your schema and query patterns. Project-scoped servers live in .mcp.json at the repo root (commit it; each teammate approves it on first run), while local and user servers live in ~/.claude.json. For the full comparison, read Agent Skills vs MCP; for config files, the mcp.json guide and the MCP config checklist.

Where plugins fit (the packaging layer)

A plugin bundles skills, subagents, hooks and MCP servers (plus LSP servers and monitors) into one installable unit, and its skills are namespaced as /plugin-name:skill-name. A CLAUDE.md at the plugin root is not loaded as context, and claude plugin validate warns about it; ship instructions as a skill instead. Plugins are distributed through marketplaces. See Claude Code plugins vs skills and Claude skills marketplaces compared.

Common mistakes

These are the placement errors that cost the most context or reliability:

• A multi-step procedure pasted into CLAUDE.md, where it loads on every request. Make it a skill.
• A safety rule written as an instruction. If it must always hold, use a hook or a deny rule.
• A subagent for work you need to steer step by step. Use a skill in the main conversation.
• An MCP server added where an existing CLI plus a skill that explains it would do the job.
• Copying .claude/ folders between repos by hand. Package the shared parts as a plugin, or install versioned skills.
• Assuming allowed-tools in a skill restricts tools. It pre-approves the listed tools for the turn that invokes the skill; use disallowed-tools or permissions to remove tools.

Share skills across repos

AIPM installs skills today; MCP and hooks packaging is on the roadmap. When a skill needs to reach more repos, install it as a versioned package instead of copying folders. --target claude writes .claude/skills/<name>/SKILL.md and --target codex writes .agents/skills/<name>/SKILL.md; Cursor reads both folders. For every team option (a committed folder, a plugin marketplace, the Claude app, managed settings, a registry), see how to share Claude skills with your team. Browse Claude skills or see the CLI commands.

npm install -g @aipm-registry/cli
aipm add @scope/name@1.0.0 --target claude   # or --target codex
aipm list                                     # what is installed (reads aipm-lock.json)

What is the difference between skills and subagents in Claude Code?

Skills are reusable instructions that run in your main conversation. Subagents are isolated workers with their own context that return only a summary.

Can Claude Code subagents use skills?

Yes. List skills in the subagent's skills: field to preload them, or let the subagent invoke them through the Skill tool. A skill can also run itself in a subagent with context: fork.

Should a rule go in CLAUDE.md or a hook?

If it must always happen, use a hook or a permissions rule. CLAUDE.md is guidance that the model may not follow every time.

Skills vs MCP: do I need both?

Often, yes. MCP adds tools and data; skills add procedures. Many setups pair an MCP server with a skill that tells Claude how to use it.

What is a Claude Code plugin for?

Packaging and sharing skills, subagents, hooks and MCP servers across repos, usually through a plugin marketplace.

What is the Cursor equivalent of CLAUDE.md?

Project rules in .cursor/rules (as .mdc files) or an AGENTS.md file, which Cursor reads in the root and in subfolders.

Does Codex have hooks and subagents?

Yes. Codex reads hooks from hooks.json or [hooks] tables in config.toml, and custom agents from TOML files in .codex/agents/ or ~/.codex/agents/.