docs: clarify child agents vs. named factory agents - #728
Conversation
Explain that multi-agent orchestration spawns ad hoc child agents from any conversation without a factory, that a child's role comes from the parent's prompt (or a skill), and that named agents with standing configuration are a Warp Factories feature dispatched by the foreman. Expand the custom-agents section on the factory agents page with an agent.md example and the skill vs. custom agent distinction, and add skills and subagents rows to the Claude Code migration table. Co-Authored-By: Warp <agent@warp.dev> Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
hongyi-chen
added
the
warpy-factory
Warp Agent Staging
|
This PR was generated with Warp. Comment   |
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![warp-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR clarifies the relationship between ad hoc child agents, reusable skills, and named Warp Factories agents across the orchestration, factory, and Claude Code migration docs. The added claims match the nearby documentation and checked source context, and the change does not introduce code or configuration with a security surface.
Concerns
- No blocking correctness, security, link, style, or spec-alignment concerns found.
spec_context.mdreports no approved or repository spec context, so there was no implementation/spec drift to evaluate.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review summary
The independent agent completed its review for this commit.
Findings
src/content/docs/platform/orchestration/index.mdx:40— [IMPORTANT] Page was already over the feature-doc word budget (1867/1500) before this PR; the new "How a child agent is configured" section (lines 40-46, ~155 words) pushes it to 2022 words with no compression-contract reasoning in the PR body's Validation section (confirmed viacheck_compression_contract.py --content-type feature-doc). Requested resolution: trim this or another section toward the 1500-word budget, or add an explicit justification to the PR body for the overage.src/content/docs/factories/factory-agents.mdx:132— [IMPORTANT] Page was already over budget before this PR (1664/1500 words, 3 callouts vs. the 2-callout limit); the expanded "Add custom agents and automations" section (~175 new words) pushes it to 1839 words with no compression-contract reasoning in the PR body. Requested resolution: trim this or another section toward budget, or add an explicit justification to the PR body for the overage.src/content/docs/factories/index.mdx:78— [SUGGESTION] The sentence chains two independent clauses plus a trailing relative clause ("...no factory required. Reach for a factory when...in one place, run by named agents that each keep their own instructions, model, harness, secrets, and MCP servers."), which is hard to scan. Requested change: split into two or three shorter sentences.src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-claude-code.mdx:91— [SUGGESTION] The "Subagents" table row packs three ideas (orchestration link, skill-migration instruction, factory-agents pointer) into one dense cell. Requested change: shorten the cell to the core equivalence and let the orchestration page's new "How a child agent is configured" section carry the skill-migration nuance.
Verdict
Request changes
| under `docs/`. Push your changes to the same branch; never merge. | ||
| ``` | ||
|
|
||
| Custom agents have no built-in skills. Add the procedures a custom agent needs as [factory skills](/factories/factory-skills/), under `agents/<name>/skills/` when only that agent should use them. If the job is a procedure an existing agent should follow rather than a separate role, a skill on that agent is enough: a skill changes what an agent knows how to do, while a custom agent has its own configuration and its own runs. For every frontmatter key, see the [`agent.md` reference](/factories/factory-as-code/#agentsnameagentmd). |
There was a problem hiding this comment.
Nit: this point about where to put agent-specific versus general skills feels kinda important but I found myself losing that key point while reading it. Maybe we can pull it out into distinct bullets?
| The factory layer adds the workflow on top: the foreman and its agents, work items that carry each request across runs, definitions as code, default automations for connected tools, and the Scorer and Self-improvement loop. | ||
|
|
||
| A standalone [cloud agent](/platform/) remains the right tool for a single task or a one-trigger automation. Reach for a factory when the work is a standing, multi-stage process your team wants to route, measure, and improve in one place. | ||
| A standalone [cloud agent](/platform/) remains the right tool for a single task or a one-trigger automation, and any agent can spawn child agents with [multi-agent orchestration](/platform/orchestration/), no factory required. Reach for a factory when the work is a standing, multi-stage process your team wants to route, measure, and improve in one place, run by named agents that each keep their own instructions, model, harness, secrets, and MCP servers. |
There was a problem hiding this comment.
Not sure if it is strictly needed here but do we document using the run_agents tool with a named agent anywhere at all?
If not, that might be worthwhile to cover since there are some interesting details to note about what values we support for the run_agents tool and how we resolve them.
2 participants
Summary
Community question (GitHub #7328, #9107): can you create Claude Code-style sub-agents outside Warp Factories, and does Factories resolve that? The docs never answered it directly. The orchestration page didn't say where a child agent's configuration comes from, the factory pages didn't distinguish factory agents from ad hoc child agents, and the Claude Code migration table had no row for subagents.
This PR answers it on the pages that own each half: orchestration spawns child agents from any conversation without a factory; a child's role comes from the parent's prompt or a skill; named agents with standing configuration are a Warp Factories feature dispatched by the foreman.
Changes
src/content/docs/platform/orchestration/index.mdx
src/content/docs/factories/factory-agents.mdx
agents/<name>/agent.md), a minimalagent.mdexample, the skill vs. custom agent distinction, and a pointer to orchestration for ad hoc child agents.src/content/docs/factories/index.mdx
src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-claude-code.mdx
.claude/skills/) and Subagents (.claude/agents/) rows to the Warp-native equivalents table.Content design plan
agent.mdfile..claude/agents/.Unverified claims
None — all UI labels, flags, defaults, and eligibility claims were verified against source.
Verification notes
warp-server/logic/factories.go(CanDispatchFactorySiblingAgents) @ d21c52498;warp/app/src/ai/blocklist/action_model/execute/run_agents.rs@ 2012bacff.skill_references:warp/crates/ai/src/agent/action/mod.rs(StartAgentExecutionMode) @ 2012bacff.warp-server/client/packages/factory/src/pages/FactoryAgents/index.tsx@ d21c52498.agent.mdfrontmatter keys (description,agentType: CUSTOM,model): existingfactory-as-code.mdxreference and the bundledfactory-filesskill examples.Documentation risk
Risk: engineering-review-required
Rationale: Adds claims about child-agent configuration, skill discovery for children, and factory-only named-agent dispatch; verified against warp and warp-server source.
Source files consulted: warp-server/logic/factories.go@d21c52498, warp/app/src/ai/blocklist/action_model/execute/run_agents.rs@2012bacff, warp/crates/ai/src/agent/action/mod.rs@2012bacff, warp-server/client/packages/factory/src/pages/FactoryAgents/index.tsx@d21c52498
Docs override: none
Validation
style_lint.py --changed: no issues in added lines (9 pre-existing bolded-term glossary warnings remain on untouched lines).check_links.py --internal-only: 0 broken links.npm run build: success.Co-Authored-By: Warp agent@warp.dev
Co-Authored-By: Oz oz-agent@warp.dev