A skill in Claude Code is the least glamorous file in your repo: a SKILL.md with some frontmatter and a body of instructions. It is also the place where a one-line change quietly moves work off your desk. That line is context: fork, and since Claude Code 2.1.218 it does two things at once — it runs the skill somewhere else, and it lets you keep working while it does. Most people find the first half in the docs and get surprised by the second. This is the piece that keeps you from being surprised.
What context: fork changes#
Add context: fork to a skill's frontmatter and the skill stops running inline. Instead, the rendered SKILL.md content becomes the prompt for a forked subagent that gets its own clean context window. That subagent does not see your main conversation history; when it finishes, only its final output comes back into your session.
---
name: audit-deps
description: Audit dependencies for known-vulnerable versions and write a report
context: fork
agent: Explore
allowed-tools: Bash(npm audit *)
---
Audit this project's dependencies for known-vulnerable versions. Read the
lockfile, cross-check advisories, and return a short prioritized report.The payoff is context hygiene: all the subagent's intermediate tool calls and reasoning stay out of your main window. You get the report, not the 40 tool calls it took to produce it. The one rule the docs are blunt about — context: fork only makes sense for a skill that contains an actual task. A skill that's just "use these API conventions" hands the subagent guidelines and no work, and it returns with nothing. (If you're weighing this against the newer Skills-vs-subagents question generally, we walked the whole tree in Claude Agent Skills vs MCP.)
The part people miss: it's in the background now#
Here is the behavior change that trips people up. A forked skill runs in the background by default. You keep working in the main session, and the result arrives in your conversation when it completes. Before v2.1.218, a forked skill always blocked the turn until it finished — so if you last read the docs a version or two ago, the default flipped under you.
The knob is one field:
context: fork
background: false # wait for the result in this turn, don't detachbackground only applies when context: fork is set, and its default is true. Setting background: false puts you back in the old blocking behavior: the turn waits for the subagent, and you get its answer before you do anything else.
The default flipped from "wait" to "walk away." If your skill's next step depends on the fork's output, you now have to ask for the wait.
Claude Code also waits for you even when you didn't ask, in two cases worth memorizing: when CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 is set (which turns off background tasks wholesale), and when you invoke a forked skill while an earlier run of the same skill is still going.
When to detach, and when not to#
The decision is really about one question: does your next step need this result?
- Fork and let it run in the background for long, self-contained, read-heavy work whose answer you'll want later — a codebase audit, a research sweep, a docs crawl. You fire it and keep moving; it pings you when it's done. This is the same instinct behind running hierarchical subagents in the Agent SDK: isolate the heavy work, keep the main thread light.
- Fork with
background: falsewhen the output feeds the very next thing you do. A background result that lands three steps too late isn't leverage, it's a race condition you built by hand. - Don't fork at all for short skills, or ones that need to see the conversation you're in the middle of. A forked subagent starts blind to your history — that's a feature for isolation and a bug for anything context-dependent.
Two gotchas that cost real time#
Detaching a skill isn't free, and both costs are invisible until they bite.
Narrower tools. A backgrounded fork runs with the reduced tool set that applies to background subagents. The skill's subagent is a regular agent type, so it doesn't get the exemption that conversation-forking subagents have. If any step in your skill depends on a tool outside that set, the run quietly can't do it — set background: false to keep the full tool set.
Checkpoints don't cover it. A background fork applies its edits outside your session's checkpoints, so /rewind won't undo them. If your skill writes files, either accept that git is now your undo button, or run it background: false so the edits fall inside checkpoint coverage.
One more sharp edge if you stack slash commands: Claude Code expands the first skill plus up to five more after it, but a skill that runs as a forked subagent — like /code-review from v2.1.218 on — ends the run there. Everything after it becomes argument text. Put your forked skill last in a chain, not in the middle.
The short version#
context: fork moves a skill into a forked subagent with a clean context. Since 2.1.218 that fork runs in the background by default — great for long, self-contained tasks, wrong for anything the next step depends on or anything needing the full tool set. Reach for background: false the moment either is true, and remember that background edits live outside /rewind. One line of frontmatter, three decisions. Now they're yours to make on purpose.
