Skills, Subagents, MCP Servers, Hooks and CLAUDE.md: What Each One Does

Spend a week with an AI coding app and someone will tell you to "add a skill", "use a subagent" or "install the MCP server", as if these meant the same thing. They don't. Each solves a different problem, loads at a different moment, and costs a different amount of context.

Below: what each piece is, how Claude Code loads it, which other apps read the same format, and a decision guide. Everything was checked against official docs in September 2026.

The short version

CLAUDE.md and AGENTS.md: always-on instructions

A project instruction file is the simplest piece: build commands, folder layout, naming rules, anything you would otherwise repeat in every chat.

Claude Code reads CLAUDE.md. It looks for it in several places:

• ~/.claude/CLAUDE.md for your personal rules across all projects
• ./CLAUDE.md or ./.claude/CLAUDE.md for the project (commit it so your team shares it)
• ./CLAUDE.local.md for personal project notes you keep out of git

All of them load at the start of every session. Anthropic's docs suggest keeping each file under about 200 lines, because longer files use more context and are followed less reliably. /init generates a starting file.

AGENTS.md is the same idea as an open, tool-neutral format. It is now stewarded by the Agentic AI Foundation under the Linux Foundation, and the agents.md site lists support in OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Jules, Aider, Zed, Windsurf, Devin, goose, opencode and others.

Claude Code does not read AGENTS.md on its own. The documented fix is a one-line CLAUDE.md that imports it:

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

A symlink (ln -s AGENTS.md CLAUDE.md) also works if you have nothing Claude-specific to add.

Use it for: facts and rules that apply to almost every task. Don't use it for: long procedures you need once a week. That is what skills are for.

Skills: know-how that loads only when needed

A skill is a folder containing a SKILL.md file. The file has YAML front matter with at least a name and a description, followed by instructions. The folder can also hold scripts, reference docs and templates.

release-notes/
├── SKILL.md
├── template.md
└── scripts/
    └── collect_commits.sh

---
name: release-notes
description: Write release notes from merged PRs. Use when the user asks for a changelog or release notes.
---

1. Run scripts/collect_commits.sh to list merged PRs since the last tag.
2. Group changes into Added, Changed, Fixed.
3. Fill in template.md. Keep each line under 100 characters.

How Claude Code loads a skill

Skills use progressive disclosure. The Agent Skills spec describes three stages:

1. Discovery: at startup the agent loads only each skill's name and description.
2. Activation: when a task matches the description, the agent reads the full SKILL.md.
3. Execution: the agent follows the instructions and opens bundled files or runs scripts only as needed.

So dozens of installed skills barely touch the context window. The description is the trigger: say what the skill does and when to use it.

In Claude Code, skills live in ~/.claude/skills/<name>/SKILL.md (personal) or .claude/skills/<name>/SKILL.md (project). You can call one directly with /skill-name, or let Claude pick it up when your request matches. Front matter such as disable-model-invocation: true makes a skill manual-only, and context: fork runs it inside a subagent.

Which apps support skills

Anthropic published Agent Skills as an open standard at agentskills.io. The client list there includes Claude Code, OpenAI Codex, Cursor, GitHub Copilot, VS Code, Gemini CLI, OpenCode, Goose, Amp, Roo Code, Kiro, Junie, Factory and many more. Folder locations differ:

• Codex: .agents/skills in the repo and $HOME/.agents/skills
• Cursor: .cursor/skills and .agents/skills, and it also reads .claude/skills and .codex/skills
• Gemini CLI: .gemini/skills or the .agents/skills alias
• OpenCode: .opencode/skills, .claude/skills and .agents/skills

So a skill you write once usually works across apps. You may just have to copy or symlink the folder.

Anthropic Agent Skills 🧩 SkillFree

Anthropic's official collection of Agent Skills, including document, design and developer skills

★ 179k · +1.2k this week

9.2 GitHub ↗

Superpowers 🧩 SkillFree

A skills library that makes coding agents plan, test-first and debug systematically

★ 294k · +2.7k this week

9.0 GitHub ↗

Browse more on the skills directory, or see which ones target a specific app at /apps/claude-code/skills.

Subagents: a separate brain for a side task

A subagent is a helper with its own system prompt, its own tool list and, most importantly, its own context window. The main agent hands it a task; the subagent reads files and runs commands, then returns only a summary.

That isolation is the point. If a test run prints 3,000 lines, none of it clutters your main conversation.

How Claude Code defines them

Subagents are Markdown files with YAML front matter, stored in .claude/agents/ (project) or ~/.claude/agents/ (personal):

---
name: code-reviewer
description: Reviews changed code for bugs, security issues and missing tests. Use after any non-trivial edit.
tools: Read, Grep, Glob
model: sonnet
---

You are a strict code reviewer. Report problems by severity. Do not edit files.

The name and description fields are required. Optional fields include tools, model, permissionMode, skills and isolation: worktree. Claude delegates automatically when a task matches the description. You can also name the subagent in your prompt or @-mention it.

Claude Code ships built-in subagents too: Explore (fast read-only search), Plan (research for plan mode) and a general-purpose agent. A subagent starts fresh: it sees your CLAUDE.md and its own prompt, but not your conversation history.

Which apps support subagents

The concept has spread, but there is no single shared file format yet:

• Codex: custom agents are TOML files in .codex/agents/ or ~/.codex/agents/, with name, description and developer_instructions.
• Cursor: Markdown files in .cursor/agents/, and it also reads .claude/agents/ and .codex/agents/.
• GitHub Copilot: agent profiles are .agent.md files in .github/agents/, and they run as subagents with a separate context window.
• Gemini CLI: Markdown files in .gemini/agents/ or ~/.gemini/agents/.
• OpenCode: Markdown files in .opencode/agents/ or ~/.config/opencode/agents/.

wshobson/agents 🤖 AgentFree

Large plugin marketplace of specialist subagents, skills and commands for Claude Code

★ 40k · +192 this week

8.8 GitHub ↗

Community collections are on the agents directory.

MCP servers: tools over a protocol

The Model Context Protocol (MCP) is an open standard for connecting AI apps to outside systems. The official site compares it to a USB-C port for AI.

The architecture has three parts. The host is your AI app, such as Claude Code. It creates one client per connection, and each client talks to one server. A server exposes three kinds of primitives:

• Tools: functions the model can call, like "open this page" or "create a GitHub issue"
• Resources: data the model can read, like a database schema
• Prompts: reusable templates

Servers run in one of two ways. Local servers use the stdio transport and run as a process on your machine. Remote servers use Streamable HTTP and usually sign you in with OAuth or a token.

In Claude Code you add them from the terminal:

# remote server
claude mcp add --transport http <name> <url>

# local server: everything after -- is the command that starts it
claude mcp add <name> -- npx -y <package>

Scopes decide where the config is saved. local (the default) is private to you in this project. project writes a shared .mcp.json you can commit. user applies to all your projects. Inside a session, /mcp shows server status.

The context cost

Every tool carries a name, description and input schema, and that metadata adds up across many servers. Claude Code now uses tool search by default, so the model discovers MCP tools as needed instead of loading all of them up front. A lean set of servers still beats a long list. Some authors now suggest a CLI plus a skill as a lighter option: the Playwright team says CLI calls are more token-efficient for coding agents, while its MCP server suits long, stateful browser sessions.

Which apps support MCP

MCP has the widest support here. Codex has codex mcp add and ~/.codex/config.toml; Cursor reads .cursor/mcp.json. VS Code with Copilot, Gemini CLI, Windsurf, Zed, Cline and Goose are MCP hosts too.

Context7 🔌 MCP serverFreemium

Up-to-date, version-specific library documentation for your coding agent

★ 63k · +180 this week

9.0 GitHub ↗

Playwright MCP 🔌 MCP serverFree

Microsoft's MCP server for browser automation with Playwright

★ 38k · +196 this week

9.1 GitHub ↗

See the full list on the MCP directory.

Hooks: rules that always run

Everything above is guidance. The model reads it and usually follows it. Hooks are different: they are shell commands that Claude Code runs at fixed points in its lifecycle, whatever the model decides.

Hooks live in the hooks block of a settings file (~/.claude/settings.json, .claude/settings.json or .claude/settings.local.json). Common events include:

• PreToolUse: before a tool runs, and it can block the call
• PostToolUse: after a tool call succeeds
• UserPromptSubmit: when you send a prompt
• SessionStart, Stop, Notification, SubagentStop, PreCompact

This example from the Claude Code docs formats every file Claude edits:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

A PreToolUse hook that exits with code 2 blocks the action and sends your message back to Claude. That makes hooks the right tool for "never edit .env" or "never run rm -rf". The docs say it directly: if something must happen at a specific point, write a hook rather than a CLAUDE.md line.

Cursor and some other apps have their own hook systems, but event names and formats are not shared.

Plugins: the package that ships the rest

A Claude Code plugin is a folder that bundles any mix of skills, subagents, hooks, MCP servers, LSP servers and slash commands, plus an optional .claude-plugin/plugin.json manifest. Plugins are distributed through marketplaces, which are Git repos with a catalog file.

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

Anthropic's official marketplace, claude-plugins-official, is registered automatically the first time you start Claude Code interactively. Plugin skills are namespaced, like /plugin-name:skill-name, so two plugins cannot clash.

The docs are blunt: plugins can run arbitrary code with your user permissions. Install only from sources you trust. The /plugin panel shows each plugin's components and estimated context cost before you install.

Decision guide: which one do I need?

Work through these questions in order.

1. Is it a fact or rule that applies to nearly every task? Put it in CLAUDE.md or AGENTS.md. Keep it short.
2. Must it happen every time, with no exceptions? Write a hook. Instructions can be ignored; hooks can't.
3. Is it a multi-step procedure or specialist know-how you need some of the time? Write or install a skill. It costs almost nothing until it's used.
4. Does the task produce lots of noise, such as logs, searches or wide reviews, when you only want the result? Use a subagent so the noise stays in its own context window.
5. Does the agent need to reach something outside your files, like a browser, GitHub, a database or live docs? Add an MCP server, or a CLI plus a skill if a good CLI exists.
6. Do you want to share any of the above with a team or the public? Package it as a plugin.

These pieces combine. A code-reviewer subagent can preload a security-checklist skill, read the pull request through the GitHub MCP server, and sit alongside a PostToolUse hook that runs your linter, all shipped as one plugin.

Common mistakes

• Stuffing procedures into CLAUDE.md. Every line costs context in every session.
• Vague skill descriptions. "Helps with docs" never triggers. Say what the skill does and when to use it.
• Relying on the model for safety. If deleting a directory would ruin your day, write a deny rule or a hook.
• Assuming formats carry over. Skills and AGENTS.md travel well. Subagent files, hooks and plugins are mostly app-specific.

Where to go next

To see which apps support which pieces, open the ecosystem compatibility map. It lays out every app in the directory against skills, subagents and MCP support. When you are ready to set things up, browse by app: /apps/claude-code/skills, /apps/claude-code/agents and /apps/claude-code/mcp. Unfamiliar terms are defined in the glossary.

Claude Code Paid

Anthropic's agentic coding tool for the terminal, IDE, desktop and web

★ 149k · +863 this week

🔥 Claude Pro billed annually: $17/month instead of $20

9.4 Visit ↗