Skills and subagents

The whole lesson in one sentence: a skill is a capability written as markdown that the model loads when it needs it, and a subagent is a fresh context window you spawn to do one job and report back.

Two ways to give an agent more

You already know the agent is a model calling tools in a loop. Now you want it to do more without drowning in instructions. There are two moves. You can hand it a capability it loads on demand. Or you can split off a separate worker that does a chunk of the job in its own context and returns a summary. Skills do the first. Subagents do the second. They compose, but they are not the same thing, and the difference is what this lesson is about.

A skill is a folder with a SKILL.md

Anthropic shipped SKILL.md on 16 October 2025 and opened it as a cross-vendor convention on 18 December 2025 via agentskills.io. The shape is trivial: a directory with at least one SKILL.md whose YAML frontmatter has two required fields.

---
name: factuur-controleren
description: Controleer facturen op BTW-correctheid en ontbrekende velden. Gebruik wanneer de gebruiker vraagt een factuur te valideren of een batch te reviewen.
---

The body is markdown: the instructions the model reads once the skill is triggered. Optionally the folder holds scripts/ and references/. No version, no license in the frontmatter. Versioning runs through git or plugin distribution.

The point is what stays out of context. Skills use progressive disclosure, three levels:

Level 1 is always in context, every session, for every skill. Level 2 loads only when the model decides this skill is relevant to the task. Level 3 loads only if the skill reaches for it. Scripts get executed, but their code never enters the context, only their output. That is the whole trick: the context stays thin until the capability actually matters.

This is model-invoked. The model reads the descriptions, decides on its own which skill fits the current task, and pulls it in. You do not route to a skill by hand. As Anthropic puts it: "MCP gives Claude tools. Skills teach Claude how to use them."

SKILL.md travels. That is the point.

In six months the format spread to 10+ harnesses: OpenAI Codex CLI, GitHub Copilot, Cursor, Gemini CLI, Cline, Amp, Factory, and more. Most read the same spec; several explicitly cross-read from .claude/skills/. Write a skill once and it works across vendors.

There is a catch worth knowing. The open spec is small: name, description, optional allowed-tools. Claude Code adds extensions (when_to_use, model, context: fork, agent, hooks, and others) that only work in Claude Code. The rule of thumb: write portable skills against the open spec, and only reach for Claude extensions when you have decided to go Claude-only.

One more thing, because skills run with real access. Snyk's ToxicSkills report (February 2026) found 13.4% of surveyed skills carry critical security issues and 36.8% have at least one flaw. Anthropic's own docs: "a malicious Skill can direct Claude to invoke tools or execute code... leading to data exfiltration." Treat third-party skills like random npm packages. Use ones you wrote, or ones from trusted sources.

A subagent is a fresh context window with a job

A subagent is a named role that runs in its own context window, with its own system prompt, a controlled subset of tools, works on its own, and returns only a summary to the main session. In Claude Code it lives in .claude/agents/*.md and you reach it through the Agent tool (renamed from Task in v2.1.63).

The contrast with a skill is the context boundary. A skill loads instructions into your current context. A subagent gets its own. So a subagent buys you two things a skill cannot: isolation and parallelism. Verbose work, like reading 40 files to find one bug, happens over there and only the answer comes back. And because each one is its own context, you can fan several out at once.

One hard limit you will hit: subagents cannot spawn subagents. The instruction is blunt: "Don't include Agent in a subagent's tools array." Nested delegation has to chain from the main conversation, or use a skill as the layer in between.

Unlike skills, subagents are a vendor silo. As of April 2026 there is no cross-vendor standard. The converter tool rulesync states it plainly: "Only Claude Code has native subagent support. The other 6 tools use SimulatedSubagent implementations... but don't provide runtime subagent functionality." The static frontmatter is roughly 80% portable; the runtime behavior is not. The likely reason, per HumanLayer's harness-engineering write-up, is that frontier models are post-trained on their harnesses. You can move a name and description. You cannot move Claude's trained instinct for when to delegate.

When to spawn vs stay single-thread

Anthropic's own split, gathered from three doc sections, is the cleanest guide:

Use	When	Example
AGENTS.md / CLAUDE.md	Project facts that must always load	Build commands, directory layout, conventions
Skill	The same playbook, repeatedly, in the main context	Invoice check, BTW rules
Subagent	Verbose output that would pollute the main context; strict tool restrictions; self-contained work	Code reviewer, researcher

Default to staying single-thread. Spawn a subagent only when one of three things is true: the work produces a lot of noise you do not want in the main thread, you want to clamp the tools tightly, or the chunk is genuinely self-contained. If you only need a repeatable procedure, that is a skill, not a subagent.

AGENTS.md: the instruction layer everyone agrees on

Sitting under both is AGENTS.md, the cross-vendor convention for an agent-definition file at the repo root. Plain markdown, no schema, no required sections. The canonical FAQ: "AGENTS.md is just standard Markdown. Use any headings you like." Since 9 December 2025 it is stewarded by the Agentic AI Foundation under the Linux Foundation, alongside MCP and goose. Over 60,000 repos use it.

The three formats divide cleanly. AGENTS.md holds project facts (setup, build, test, style, PR). SKILL.md holds per-task capabilities. Subagents hold roles with context isolation. AGENTS.md and SKILL.md are portable across harnesses. Subagents are not.

Claude Code is the one structural exception on AGENTS.md: it does not read the file natively. The official workaround is a single @AGENTS.md import line in CLAUDE.md, with up to 5 recursive hops. Vercel's next.js repo does the inverse and symlinks CLAUDE.md to AGENTS.md.

There is a finding worth holding onto. An ETH Zurich study (Gloaguen et al., arXiv, February 2026) found that LLM-generated AGENTS.md files lowered success rate in 5 of 8 settings while adding 20-23% token cost. Hand-written files gave a small +4% correctness. The rule: write AGENTS.md by hand, keep it short, use the standard sections. Longer auto-generated files hurt. The same pattern, per two follow-up studies, holds for content primitives in general: hand-written minimal beats machine-written verbose.

How they compose

In Claude Code the three primitives stack in both directions. A subagent can use a skill: declare it in skills: frontmatter and the whole skill loads into the subagent at startup, or it pulls the skill dynamically during the run. A skill can spawn a subagent: set context: fork plus an optional agent: field, and the skill body becomes the subagent's prompt.

The strategic line: put procedural knowledge in skills, because skills are portable and migrate to any harness. Put roles that need context isolation in subagents, because that value is Claude-specific but cheap to rewrite (~100 lines of markdown per role). Put project facts in AGENTS.md. If you ever switch harness, your skills and AGENTS.md travel with you, and you rewrite a few subagent definitions by hand.

Takeaways

• A skill is a capability in a folder: SKILL.md plus optional scripts, loaded by progressive disclosure so context stays thin until it matters. Portable across 10+ harnesses.
• A subagent is a fresh context window with its own tools that returns only a summary. It buys isolation and fan-out. Claude-only, and it cannot spawn another subagent.
• Default single-thread. Spawn a subagent for noisy, tightly-scoped, or self-contained work. Reach for a skill for a repeatable procedure.
• AGENTS.md is the portable instruction layer. Write it by hand and keep it short: LLM-bloated files measurably hurt.
• Procedural knowledge to skills, isolated roles to subagents, project facts to AGENTS.md.

Where this goes next

You have now seen how to package capability and split off work. But every skill that runs code and every subagent with Bash in its tools array raises the same question: how much should the agent be allowed to do on its own before it asks you? That is the subject of the next lesson, "Permissions and the autonomy slider," where the silo formats stop being a footnote and start mattering.