[DOCS] Skills docs omit that `context: fork` runs in the background by default
Documentation Type
Missing documentation (feature not documented)
Documentation Location
https://code.claude.com/docs/en/skills
Section/Topic
“Run skills in a subagent” and the frontmatter reference for skills with context: fork.
Current Documentation
The page currently says:
Add context: fork to your frontmatter when you want a skill to run in isolation. The skill content becomes the prompt that drives the subagent.
The frontmatter table describes context: fork and agent, but has no background field or default behavior.
What's Wrong or Missing?
Claude Code 2.1.218 changed skills with context: fork to run in the background by default. A skill author can opt out with background: false.
The current page explains isolation but not whether the caller waits for the forked skill, where its progress appears, or how an author can preserve foreground behavior. This is a meaningful execution and interaction change for skills that depend on a result returning before the main turn continues.
Suggested Improvement
Document the background frontmatter field next to context:
backgrounddefaults totruewhencontext: forkis set, so the forked skill runs as background work and its result is reported when it completes.- Set
background: falseto keep the forked skill in the foreground when the invoking workflow must wait for the result.
Add an example for both forms and explain how users monitor and stop the resulting background task. Clarify whether the setting affects only context: fork skills or is ignored for inline skills.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/skills | context: fork execution and frontmatter reference |
| https://code.claude.com/docs/en/sub-agents | Forked subagent execution and result handling |
Total scope: 2 pages should describe the same forked-skill execution contract.
The behavior was changed in Claude Code v2.1.218.
3 Comments
This default flip is more than a documentation gap: it silently breaks the output contract of existing
context: forkskills.Before this change, a forked skill's final message rendered directly as the response, verbatim. Since 2.1.218, the skill runs in the background and its result is delivered to the main agent as a
<task-notification>, which then relays it. In practice that means paraphrasing and compressing it, so formatting and detail are lost. For skills whose final message is the deliverable, that output gets lost in translation. Nothing about the skill changed; only the CLI version did.The change is mentioned in the release notes ("Changed skills with
context: forkto run in the background by default; opt out per skill withbackground: false"), but that's part of the problem: a breaking change to skill execution semantics is buried in a one-line changelog entry, with no update to the docs it contradicts. Anthropic really needs a better channel for communicating breaking changes than expecting users to diff release notes against the documentation.So beyond documenting the
backgroundfield: please treat default flips like this as breaking changes and call them out prominently — a highlighted "breaking changes" section in the release notes at minimum, ideally a deprecation/transition period where the old default still applies unless opted in.Thanks — this is now documented.
The skills page describes that a
context: forkskill runs in the background by default (v2.1.218+), that its result arrives in your conversation when it completes, and thatbackground: falsemakes the invoking turn wait for the result. It also lists the cases where Claude Code waits regardless and the narrower tool set a backgrounded fork gets: https://code.claude.com/docs/en/skills#run-skills-in-a-subagent. Thebackgroundfield is in the frontmatter reference on the same page.Closing as answered — reopen if the subagent page still needs a cross-reference.
🤖 Generated with Claude Code
This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.