You wrote a subagent and it keeps asking about things you explained to Claude ten minutes ago. Or you wrote a skill and it never fires. Both are the same mistake: reaching for the wrong one of three things that look alike on disk and behave nothing alike at runtime. Here is the real line between them, a table for picking one, and two files to copy.
Key takeaways
- A skill is instructions Claude loads when it recognises the job. It runs inside your conversation and changes how the work gets done.
- A subagent is a separate Claude with its own context window and tool allowlist. It changes where the work happens and what comes back.
- MCP is neither: a connection to an outside system, changing what Claude can reach.
- A skill changes how, a subagent changes where. Most bad setups pick the wrong axis. They also compose: a subagent can preload named skills, and a skill can run in a forked subagent.
- Both are static text. The facts they depend on are not, which is where setups quietly rot.
---
What a Claude skill actually is
A skill is a folder with a SKILL.md inside it. The frontmatter says what it is for; the body is the instruction set Claude follows once it is in play. Personal skills sit at ~/.claude/skills/<name>/SKILL.md and follow you between projects. Project skills sit at .claude/skills/<name>/SKILL.md and reach your team when they pull the repo.
The mechanism worth understanding is progressive disclosure. At session start Claude reads your skills' descriptions, not their bodies. The body stays on disk, costing nothing, until Claude decides a request matches. That is why a 400-line reference document is a reasonable skill and a 400-line block in CLAUDE.md is not.
It also means the description is the trigger. If your skill never fires, the description is almost always the bug. Write it as "what this does, and when to use it", using the phrases a real person would type, and put the use case first: Claude Code truncates the combined description at 1,536 characters in the skill listing.
One bit of housekeeping settles an old confusion: slash commands and skills have merged. .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both give you /deploy; the skill form just adds a folder for supporting files. For the full anatomy, see our walkthrough of Claude Code skills.
What a subagent actually is
A subagent is a Markdown file at .claude/agents/<name>.md (project) or ~/.claude/agents/<name>.md (personal). The frontmatter configures it; the body is its system prompt.
What makes it a subagent and not a skill is the context window. When Claude delegates, it starts fresh: its own system prompt, a task message describing the work, your CLAUDE.md hierarchy, and the current git status. It does not receive the conversation you have been having.
That is the most common surprise, so state it flatly: a subagent does not inherit your conversation. Not the files Claude already read, not the decision you made three messages ago. If it matters, it goes in the delegation prompt, the agent's system prompt, or CLAUDE.md.
The isolation is a cost when you wanted continuity and the entire point when you wanted independence. A subagent reviewing code it did not write has no attachment to the approach, and its own tool allowlist means tools: Read, Grep, Glob guarantees it cannot edit anything.
Where MCP fits, and why it keeps getting mixed in
MCP shows up here because people meet all three in the same week and file them in the same drawer. They belong in different drawers.
MCP is an open protocol for connecting Claude to an outside system: an issue tracker, a database, a design tool, your own service. It gives Claude reach. It does not give Claude judgement about how to use that reach, which is what a skill is for.
The clean split:
- Skill: does Claude know how we do this?
- Subagent: should this work happen somewhere else and come back as a summary?
- MCP server: can Claude get to the thing at all?
Connect an MCP server to your issue tracker and Claude can read tickets. Write a skill and Claude knows your team puts acceptance criteria in the description, never the comments, and that a ticket without them gets sent back. Different problems, and solving one does not solve the other. We go deeper on the connection layer in connecting Claude to your memory over MCP.
Here they are side by side.
| Skill | Subagent | MCP server | |
|---|---|---|---|
| What it is | Instructions Claude loads when it recognises the job | A separate Claude with its own context window | A connection to an outside system |
| Where it lives | .claude/skills/<name>/SKILL.md | .claude/agents/<name>.md | .mcp.json at the project root, or ~/.claude.json |
| What it changes | How the work is done | Where the work happens, and what returns | What Claude can reach |
| What triggers it | Claude matching the description, or you typing /name | Claude delegating, or you naming the agent | A tool call, once the server is connected |
| Context cost | Just the description, until it fires | A second full context window | Its tool definitions, from session start |
| Sees your conversation | Yes, it runs inside it | No | Not applicable, it is a pipe, not a reader |
---
Skill, subagent, or MCP server: a decision table
Start from the job, not the feature.
| The job you actually have | Reach for | Why |
|---|---|---|
| "Always write commit messages our way" | Skill | A procedure needed inside the current work. Cheap until it fires |
| "Review this change as if you had not just written it" | Subagent | The clean slate is the value. A skill cannot give you one |
| "Read our issue tracker" | MCP server | Nothing to do with instructions. Claude cannot reach the system at all |
| "Find every place we handle auth across 400 files" | Subagent | High-volume reading. Keep the noise out of your main thread |
| "Format charts to our brand palette" | Skill | Procedure plus reference material that loads only when charts come up |
| "Run three independent reviews at once" | Subagents, in parallel | Separate contexts is the whole point |
| "Query the read replica, with no write access" | MCP server plus a restricted subagent | MCP is the connection, the agent's tools allowlist is the safety rail |
| "A long procedure that floods the main thread" | Skill with context: fork | Runs the skill in a subagent and returns only the result |
Two failure modes fall out of that table. The first is a long agent file that is really just a procedure: you pay a cold start and lose your conversation every time, for nothing. The second is a noisy job left in a skill, flooding your main context with file dumps nobody reads.
Two files you can copy
A real skill. Short frontmatter, a body that is opinionated about output:
---
name: pr-description
description: Writes a pull request description in our house format. Use when the user asks for a PR description or a PR body, or says they are opening a PR.
---
## The diff
!`git diff origin/main...HEAD`
## Instructions
Write the description in exactly these three sections:
1. **What changed.** Two or three bullets in plain English. No file paths.
2. **Why.** One sentence, tied to the ticket if there is one.
3. **How to test.** The exact commands a reviewer runs.
Never add a "Summary of changes" heading. Never list every file touched.The ` !git diff origin/main...HEAD ` line runs before Claude sees the skill, so the instructions arrive with the real diff already inlined.
A real subagent. Note the read-only tool list and the instruction to behave like a stranger:
---
name: api-reviewer
description: Reviews API changes for breaking contracts and missing validation. Use after any change under src/api/.
tools: Read, Grep, Glob
model: sonnet
---
You are reviewing an API change with no knowledge of the conversation that produced it. Do not assume the author was right.
Check, in this order:
1. Does any response field change shape or disappear? That is a breaking change. Say so first.
2. Is every new input validated at the boundary, not deep inside a handler?
3. Does the change match the error format already used elsewhere in this codebase?
Return at most five findings, each with a file path and a line number.
If you find nothing, say so in one line and stop.Take the same job, "make sure API changes get reviewed", and watch the two behave differently. As a skill it runs in your current thread, fast and cheap, but the reviewer is the same Claude that just wrote the code and is still carrying its reasons for thinking it fine. As a subagent it costs a cold start and more tokens, and buys a reader with no stake in the answer and no way to quietly fix what it finds.
You can also combine them: a subagent's skills: field preloads named skills into its fresh context, so an isolated reviewer gets your house conventions without pasting them in.
Where skills come from, and how to choose between them
Three sources, in ascending order of effort: the ones bundled with Claude Code, the ones you install, and the ones you write.
Write your own when the procedure is specific to your codebase or house style, because nobody else can. Install for the generic craft: review checklists, and the writing, design and research procedures that are the same everywhere.
When choosing between installable skills, judge them on three things. Is the description written as a trigger or as marketing? Is the body a real procedure with steps and constraints, or a vague statement of good intentions? And has anyone run it and compared the output to not running it? Almost nobody publishes that last part, which makes it the fastest way to spot a tested skill. If you want a starting point, we publish a directory of 114 Claude skills that installs as a Claude Code plugin marketplace with /plugin marketplace add mkhalid1/locul-skills; five carry measured before-and-after results, six more were tested and cut, nineteen were retired, and the testing method is published alongside them.
Whatever you install, prune it. Forty skills you never fire is forty descriptions competing for Claude's attention every session.
---
What breaks six months in
Here is the part the comparisons skip, because it does not show up on day one.
A skill is a text file. A subagent is a text file. Both encode a procedure, and procedures are reasonably stable. What is not stable is everything the procedure depends on: which model you standardised on, what your pricing actually is now, the feature you removed that the checklist still tests for, the convention you changed in February and never wrote down.
None of that fails loudly. The skill still fires. The subagent still returns its five findings. They are just reasoning from last quarter's facts, confidently, in your voice.
A skill that fires perfectly on last quarter's facts is still wrong. It just fails quietly.
There are two honest fixes and you want both. The first is discipline: keep facts out of your skills and agents. A skill should say how you review an API, not what your current rate limits are. The moment a specific number lands in a SKILL.md, you have signed up to maintain it by hand forever, and you will not. We go through the audit in keeping an AI setup current.
The second is having somewhere for those facts to live that updates without you. That is the problem Locul was built for: a local-first desktop app for macOS and Windows that builds a second brain from what you already produce, your Markdown notes, PDFs, dictation, Notion pages and LinkedIn profile, keeps it current as those change, and serves it to Claude over MCP. When a fact changes, the old memory is marked superseded and the new one takes over, so your skills stay short and procedural while the facts underneath them stay right. That division of labour is also the cleanest way to think about skills versus memory, and it sits inside the broader question of giving your AI memory that lasts.
FAQ
What is the difference between Anthropic skills and agent skills?
Two names for one thing. "Agent Skills" is the open standard, published at agentskills.io, that defines the SKILL.md format; Anthropic's products call them skills. A skill you write for Claude Code is a plain SKILL.md folder other tools implementing the standard can also read. Claude Code layers extra frontmatter on top, such as invocation control and forked execution; those extras will not travel.
What is the difference between Claude and a Claude agent?
Claude is the model you are talking to. A Claude agent is a configured instance of it: a named file with its own system prompt, tool allowlist and fresh context window that the main conversation delegates work to. In Claude Code these are subagents, in .claude/agents/. Underneath it is the same model unless you set another with the model field. What changes is the setup and the clean slate, not the intelligence.
Does Claude read agent skills?
Yes, but selectively. At session start Claude reads only the name and description of each available skill, not the body. It loads the body when it judges the request matches, which is why the description decides whether your skill ever runs. Subagents are separate: they do not inherit the skills the main conversation loaded. To give a subagent a skill, name it in that agent's skills: frontmatter field.
Is Claude or ChatGPT better for agents?
For most people this is a tooling question, not a model question. If your work lives in a terminal and a repository, Claude Code is hard to beat on one axis: skills and subagents are plain files in your project, reviewed and versioned like code, so a teammate gets your setup by pulling the branch. If your work is in a browser and in documents, the gap narrows, so test both on your own tasks. Either way the failure mode is identical: both give you static instruction files that go stale at the same rate.
Can you use a skill and a subagent together?
Yes, in both directions, and this is where most good setups end up. A subagent can preload skills by listing them in its skills: frontmatter, which gives an isolated worker your house conventions without pasting them into every prompt. Going the other way, a skill can carry context: fork, which runs it inside a forked subagent and returns only the result to your main thread.
Where to go next
The decision is simpler than the terminology suggests. Ask whether you need a procedure, a clean room or a connection, then pick the one thing that answers it. Keep descriptions short, keep specific facts out of your instruction files, and prune what you never fire.
If that last part is where you keep losing, Locul is free to start: 500 active memories, local AI, no credit card, on macOS and Windows. Download it and point Claude at a brain that keeps itself current, instead of a folder of files you have to remember to edit.
