Claude Agents, Skills, AGENTS.md: The 2026 Disambiguation Map

In the last two weeks, Anthropic shipped three product launches that each added a new word to the Claude vocabulary. May 6 brought multiagent orchestration, dreaming, and outcomes to Claude Managed Agents. May 12 brought Agent View, the claude --bg flag, and the /goal command to Claude Code. May 13 layered Claude for Small Business on top with another fifteen agentic workflows. Add the pre-existing Skills, sub-agents, agent teams, CLAUDE.md, and the emerging AGENTS.md cross-tool standard, and you have eleven words that all sound related and almost nobody uses correctly.

The smartest developers on X are confused too. The most-shared post about the launch week is a thread titled “Claude Code ships with 5 architectural layers most engineers never open.” The most useful real-world tip from the same week is a one-liner: “Skills live at ~/.claude/skills/<name>.md. Sub-agents live at ~/.claude/agents/<name>.md. Mixing them is the most common reason a skill silently doesn’t load.” If practitioners are mixing up the folders, the rest of us need a map.

This post is the map. One mental model, one comparison table, one decision tree.

Source: Anthropic — Agent view in Claude Code

The mental model: three layers, two places

Before any of the words, hold this in your head:

There are two places Claude runs. The first is Claude Code — the CLI on your laptop, where you and a developer-shaped Claude sit in a terminal together. The second is the Claude Platform (formerly the Anthropic API surface) — the cloud, where Claude runs as a managed service that other systems talk to.

There are three kinds of things that show up in both. Capabilities (Skills) plug knowledge into Claude. Workers (agents in all their flavors) do tasks. Context files (CLAUDE.md, AGENTS.md) give the workers their starting facts about your project.

Everything below is a specialization of one of those six cells. Once you internalize the matrix, the new words stop sounding like new concepts and start sounding like obvious combinations of existing ones.

Six cells. Eleven words. Let’s walk through each one.

(1) Skills

What it is. A modular, named capability — a folder with instructions, optional scripts, and optional resources — that Claude can auto-load when it judges the skill relevant to the task. Skills are not system prompts; system prompts load once at session start and never change. A skill is a file Claude discovers, evaluates for relevance, and pulls in dynamically.

When it shipped. Anthropic introduced Agent Skills in mid-2025 and has continued to expand the format through 2026. The Claude Platform now treats Skills as a first-class concept; the Claude Code client reads them from disk.

Where it lives. In Claude Code, skills live at ~/.claude/skills/<skill-name>/SKILL.md (with optional scripts and resources in the same folder). On the Claude Platform, skills can be attached to Managed Agents as capabilities. The format is the same in both places.

File format. A folder with a SKILL.md that has YAML front-matter (name, description, optional metadata) followed by natural-language instructions and optional pointers to scripts or resource files.

Canonical use case. “I need Claude to follow a specific internal procedure every time the topic comes up.” Examples: enforce house coding style, write PR descriptions in your template, format a legal memo to your firm’s house standard, run a security review using your team’s threat-model checklist.

One-line summary: Skills are knowledge that Claude pulls in when relevant.

(2) Sub-agents

What it is. A named specialist Claude — its own system prompt, its own tool permissions, its own conversation context — that the main Claude can delegate work to and get an answer back from. Sub-agents map cleanly to the “team of specialists” pattern: a Security Reviewer, a Performance Profiler, a Data Scientist, each opinionated about its niche.

When it shipped. The /agents flow and sub-agent file format were documented in mid-2025. The pattern matured throughout late 2025 and into 2026.

Where it lives. Claude Code only. Sub-agents are a local-CLI concept; they don’t live on the Claude Platform under that name. The Platform’s equivalent is the lead-agent-plus-specialists pattern inside Managed Agents (see #4).

File format. Markdown files at .claude/agents/<agent-name>.md (project-local) or ~/.claude/agents/<agent-name>.md (global, cross-project), each with YAML front-matter and a system-prompt body. Usually managed through the /agents slash command rather than hand-edited.

Canonical use case. “I want a dedicated, reusable agent for a role, not a one-off prompt.” Example: a Security Reviewer sub-agent that runs threat modeling and static analysis on every PR while you keep working with the main Claude.

One-line summary: Sub-agents are named specialist workers you can call by job title.

Source: Claude Code Docs — Create custom subagents

(3) Background agents (claude --bg, /bg)

What it is. A runtime mode — not a file format, not a new agent type — that detaches a Claude Code session from your terminal so it keeps running after you close the window. The supervisor process keeps the session alive; Agent View is the dashboard that lets you see all your background sessions in one list.

When it shipped. Claude Code 2.1.139, around May 12, 2026, alongside Agent View.

Where it lives. Claude Code only. You promote any existing session to a background session with the /bg slash command, or you start one in background mode with claude --bg [task] from the CLI.

File format. None — it’s a runtime mode applied to a session, not a thing you author. Sessions are tracked by the supervisor and visible in Agent View.

Canonical use case. “I have a slow, heavy task and I don’t want to babysit it.” Examples: refactoring a monorepo component tree, running a long diagnostic across server logs, executing a migration that touches hundreds of files.

One-line summary: Background agents are Claude Code sessions running detached, observable through Agent View.

(4) Multiagent orchestration (Managed Agents feature)

What it is. A feature of Claude Managed Agents — the Claude Platform’s cloud product — where a lead agent can spin up specialist agents in parallel on a shared environment (filesystem, container) and coordinate their work. Each specialist has its own context window; they share the workspace so they can hand artifacts back and forth.

When it shipped. May 6, 2026 (Managed Agents launch, alongside Dreaming and Outcomes).

Where it lives. Claude Platform only. This is the cloud-runtime analog of the local sub-agents pattern, but it’s a managed feature with explicit orchestration primitives, not a CLI behavior.

File format. Configured through the Claude Platform’s agent-definition surface (API/console). No SKILL.md or .claude/agents/ involved.

Canonical use case. “I want a cloud workflow where a lead Claude coordinates a few specialist Claudes on a shared filesystem and returns a single result.” Examples Anthropic highlighted at launch: Harvey running 6× more completions per dollar, Wisedocs cutting document review time in half.

One-line summary: Multiagent orchestration is cloud-side lead+specialist delegation with a shared workspace.

Source: Anthropic — New in Claude Managed Agents

(5) Agent Teams (Claude Code)

What it is. A 2026 pattern where multiple independent Claude Code instances communicate with each other directly — no lead, no central orchestrator. Think of it as a chat between Claudes that hands off work the way two engineers would in a Slack thread.

When it shipped. February 5, 2026.

Where it lives. Claude Code. Agent Teams reuse the same .claude/agents/ file format as sub-agents — there is no syntactic difference. The distinction is behavioral: a sub-agent reports back to a lead; an agent team member has a peer relationship with the other members.

File format. Same as sub-agents (.claude/agents/<name>.md). The pattern is enforced at runtime, not in the file.

Canonical use case. “I want a sprint-like collaboration between two or three Claudes, each with their own perspective, who can disagree, debate, and resolve.” Useful for code review chains, multi-perspective writing tasks, or any work that benefits from explicit dissent.

One-line summary: Agent Teams are peers that talk to each other instead of reporting up to a lead.

(6) Managed Agents (Claude Platform product)

What it is. The umbrella product name for Anthropic’s cloud agent runtime. Managed Agents is where Skills, multiagent orchestration, Dreaming (between-session memory consolidation), Outcomes (rubric-graded success criteria), and the API-level webhook system all live as features.

When it shipped. The Managed Agents product has been live throughout 2026. The big May 6 launch added Dreaming, Outcomes, and Multiagent Orchestration in one release.

Where it lives. Claude Platform (cloud) only. You interact with it via the API or the console.

File format. None at the user level — Managed Agents are configured through the Platform, not authored as files.

Canonical use case. “I want Claude to run as a managed service for my product, my back-office workflow, or my customer-facing system, with cloud-grade reliability and the orchestration primitives my workload needs.” Anthropic’s launch customers include Harvey (legal), Wisedocs (insurance), and Netflix (build-log parallelization).

One-line summary: Managed Agents is Claude-as-a-managed-service, the cloud counterpart to Claude Code.

(7) CLAUDE.md vs AGENTS.md

What they are. Both are project-context files — markdown documents that sit in your repository and brief any AI coding tool about the codebase before it starts work. The distinction is portability.

CLAUDE.md is Anthropic’s native format, read by Claude Code only. Claude walks up the directory tree from your working folder and concatenates every CLAUDE.md it finds, with the closest file taking precedence. It supports @ imports (you can reference other files inside CLAUDE.md and Claude will pull them in).

AGENTS.md is the emerging cross-tool standard, read by OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, and many others. The format is plainer markdown — no imports, no Claude-specific syntax. Over 60,000 repos including n8n have adopted it.

The 2026 best practice from the community: put your project context in AGENTS.md, and have CLAUDE.md import it with a single line — @AGENTS.md. One file on disk, two filenames, zero drift, every coding agent reads the same context.

Canonical use case. Any team using more than one AI coding tool, or any team that thinks they might switch tools in the next year, should default to AGENTS.md and let CLAUDE.md be a thin Claude-specific extension.

One-line summary: CLAUDE.md is Claude-only project context; AGENTS.md is the cross-tool standard. Use AGENTS.md as the primary, with CLAUDE.md as a thin Claude-flavored wrapper.

The decision tree

When you find yourself reaching for a Claude feature this week, walk down this list and stop at the first match:

• I want Claude to follow a specific procedure every time a related task comes up. → Skill.
• I want a dedicated Claude wearing a job title (Security Reviewer, Data Scientist, Debugger). → Sub-agent.
• I want my current Claude Code session to keep running after I close the terminal. → /bg or start with claude --bg.
• I want to see and switch between all my detached sessions in one list. → Agent View.
• I want a cloud Claude that coordinates specialists in parallel on a shared filesystem. → Managed Agents with multiagent orchestration.
• I want two or three Claudes to debate and hand off work like peers, not boss/employee. → Agent Teams.
• I want Claude to know my project’s house rules before it writes a single line. → AGENTS.md (with CLAUDE.md importing it via @AGENTS.md).
• I want Claude-as-a-product baked into my SaaS, my back-office, or my customer support flow. → Managed Agents.
• I want my Claude to “remember” what it learned between sessions on the same agent. → Dreaming (a Managed Agents feature).
• I want my Claude to grade itself against a rubric and self-improve. → Outcomes (a Managed Agents feature).

If none of the above match, you probably want a regular Claude Code session and a clear prompt. The pattern menu exists because pattern proliferation is real, not because every task needs a pattern.

The comparison table

The bug that catches everyone: folder confusion

Per a viral tip on X from May 14: “Skills live at ~/.claude/skills/<name>.md. Sub-agents live at ~/.claude/agents/<name>.md. Different folders, different runtime contexts. Mixing them is the most common reason a ‘skill’ silently doesn’t load.”

That is the single most useful sentence in this whole post. The two folders look almost identical, the file names rhyme, and a markdown file dropped in the wrong folder produces zero error — it simply never activates. If a skill or sub-agent you wrote isn’t being picked up, check the folder first, the file format second, the YAML front-matter third. In that order. The folder is the silent killer.

The same trap applies on the cloud side. Skills attached to a Managed Agent need to be configured in the Platform; sub-agent-style specialists are spun up at runtime by multiagent orchestration; CLAUDE.md and AGENTS.md don’t apply to Platform agents at all. Mixing local conventions with cloud conventions is a common cause of “why did my agent not see the rules?”

What this means for you

If you are a solo developer using Claude Code on side projects: you almost certainly only need Skills, CLAUDE.md (or AGENTS.md), and the occasional /bg for long jobs. Sub-agents are useful once you have a workflow you repeat enough to justify giving it a name. Agent Teams and multiagent orchestration are overkill for solo work — skip them until they earn their place.

If you run an engineering team that already uses Claude Code in CI or local dev: standardize on AGENTS.md (Claude reads it, every other coding tool reads it, zero lock-in) and a small library of Skills checked into the repo. Add a sub-agent only when a role keeps recurring across PRs (“the Test Plan Writer,” “the Migration Reviewer”). Agent View is the daily-driver upgrade — install Claude Code 2.1.139 and use it.

If you’re building Claude into a product (SaaS, back-office, customer support flow): Managed Agents is the right surface. Use Skills for capabilities you want the agent to acquire, multiagent orchestration when one big task naturally splits into specialist subtasks, and the new Outcomes rubric to grade and self-improve. Skip the Claude Code patterns — they’re a different runtime for a different audience.

If you’re an AI consultant or agency: the disambiguation itself is the deliverable. Most prospects know they want “AI agents” but can’t articulate whether they need a local CLI workflow (Claude Code with sub-agents and Skills) or a cloud-grade product (Managed Agents with orchestration). Walking a client through the map above is the first hour of any agent engagement.

What this map doesn’t cover

This post deliberately leaves out a few adjacent concepts to keep the map readable. If you want to go deeper, they are:

• MCP (Model Context Protocol) — the protocol Claude (and increasingly other models) use to talk to external tools and data sources. MCP servers are how a Claude sub-agent gets access to your database, your Linear, your filesystem outside its sandbox. Out of scope here, but every agent worth shipping uses at least one MCP.
• Plugins — packaged combinations of slash commands, hooks, agents, MCP servers, and skills bundled as a single installable unit. The package format; not a separate runtime.
• Hooks — lifecycle callbacks that run shell commands at specific events (e.g., before tool use, after a write). Useful for safety guardrails; not an agent pattern per se.
• CLAUDE.md @imports — the syntax for pulling other files into your Claude-Code context. Used to wire CLAUDE.md to AGENTS.md cleanly.

Any one of those would be a post of its own.

The bottom line

The Anthropic vocabulary explosion of 2026 is genuinely confusing — even the people building on it daily mix up folders. The fix is to hold the matrix in your head: two places (Claude Code, Claude Platform), three layers (capabilities, workers, context). Every new word that lands in your feed is a specialization of one of those six cells. Eleven words. Six cells. One decision tree.

If you want the hands-on version of this map, our Multi-Agent AI Systems course walks through the patterns module by module, our Claude Code Mastery course covers the daily-driver workflows (Skills, sub-agents, Agent View), and our AI Agents Deep Dive covers when to reach for Managed Agents and cloud orchestration instead of the local CLI patterns. Three different entry points; same underlying map.

The next time Anthropic ships another launch with three new words in it, you’ll know which cell each one drops into before you finish reading the changelog.

Sources

• Anthropic — Agent view in Claude Code (May 12, 2026)
• Anthropic — New in Claude Managed Agents (May 6, 2026)
• Claude Code Docs — Create custom subagents
• Claude Code Docs — Skills (Agent Skills)
• AGENTS.md vs CLAUDE.md: Real Differences & When to Use Each (2026)
• Claude Skills vs Agents: Differences (2026) — Verdent
• Sub-agent vs. Agent Team in Claude Code: Pick the Right Pattern in 60 Seconds
• How to Use Claude Code’s /bg Command for Background Agent Sessions
• Anthropic Managed Agents vs. Agent SDK comparison