docs: clarify child agents vs. named factory agents

src/content/docs/factories/factory-agents.mdx

@@ -131,7 +131,24 @@ With a Warp-managed factory, you can edit harness, auth, and model from the dash
 
 ## Add custom agents and automations
 
-Add custom agents for jobs the default agents don't handle, such as documentation, security analysis, migrations, or release checks. A custom agent doesn't have to be a required step for every work item.
+Add custom agents for jobs the default agents don't handle, such as documentation, security analysis, migrations, or release checks. A custom agent is a named agent with its own instructions, model, harness, secrets, and MCP servers. The foreman dispatches it by name when a work item calls for it, so it doesn't have to be a required step for every work item.
+
+On a Warp-managed factory, add one from the **Agents** page in the [factory dashboard](/factories/factory-dashboard/): click **New**, then **Custom agent**. On a GitHub-backed factory, add an `agents/<name>/agent.md` file, where the frontmatter holds the configuration and the Markdown body holds the instructions:
+
+```markdown title="agents/docs-writer/agent.md"
+---
+description: Updates user-facing docs when a change affects documented behavior
+agentType: CUSTOM
+model: auto
+---
+
+Read the pull request the foreman hands you and update the affected pages
+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).
+
+Factory agents run in the cloud as part of a work item. To spawn ad hoc child agents from any Warp conversation, no factory required, see [multi-agent orchestration](/platform/orchestration/).
 
 Automations start a chosen agent on a [schedule](/factories/factory-as-code/#triggersschedule) or when an event fires. They're one more way for work to enter your factory; the foreman still coordinates whatever they start. For all the ways to route work into a factory, see [connect your factory](/factories/connect-your-factory/).
 

src/content/docs/factories/index.mdx

@@ -75,7 +75,7 @@ Warp Factories is built on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overv
 
 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.
 
 ## Key terms
 

src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-claude-code.mdx

@@ -87,6 +87,8 @@ Use this table to find the closest Warp equivalent for Claude Code concepts:
 | `CLAUDE.md` | `AGENTS.md` (or `WARP.md`) at the project root, picked up as a [Rule](/agents/capabilities/rules/) |
 | Claude Code slash commands | Warp's own [slash commands](/agents/capabilities/slash-commands/) (`/init`, `/plan`, `/model`, etc.); save your own as [Warp Drive prompts](/knowledge-and-collaboration/warp-drive/prompts/) |
 | Tool definitions | [MCP](/agents/capabilities/mcp/) |
+| Skills (`.claude/skills/`) | [Skills](/agents/capabilities/skills/); Warp discovers `.claude/skills/` as-is, alongside `.agents/skills/` and the other supported directories |
+| Subagents (`.claude/agents/`) | [Multi-agent orchestration](/platform/orchestration/) spawns child agents from any conversation; move each subagent's prompt into a skill and ask the parent to have the child use it. For named agents with standing configuration, see [factory agents](/factories/factory-agents/) |
 | Resume conversation | Warp persists agent conversations per tab; pair with [tab configs](/terminal/windows/tab-configs/) to reopen the same project layout |
 
 For a deeper tour of Agent Mode, see [Coding in Warp](/getting-started/quickstart/coding-in-warp/) and the [Agents overview](/agents/).

src/content/docs/platform/orchestration/index.mdx

@@ -13,7 +13,7 @@ Watch this walkthrough to see how a cloud agent can coordinate a team of agents
 
 <VideoEmbed url="https://www.youtube.com/watch?v=qeR79bhyFOw" title="How to orchestrate a team of agents in the cloud with Warp" />
 
-This page covers the orchestration model and the patterns it supports. To learn how to start an orchestrated run, see [Running orchestrated agents](/platform/orchestration/multi-agent-runs/).
+To start an orchestrated run, see [Running orchestrated agents](/platform/orchestration/multi-agent-runs/).
 
 To orchestrate work inside a [Warp factory](/factories/), dispatch through the [factory API](/factories/factory-api/) instead of calling `POST /agent/runs` with the foreman's `agent_identity_uid` directly. The server resolves the foreman for you, and everything on this page still applies to the run it starts.
 
@@ -37,6 +37,14 @@ The parent and child don't have to run in the same place. Orchestration supports
 
 Children can also run with a different agent runtime than the parent. A parent running with the default Warp Agent can spawn children that run with [Claude Code](/agents/cli-agents/claude-code/) or [Codex](/agents/cli-agents/codex/), and vice versa.
 
+### How a child agent is configured
+
+A child agent has no definition file of its own: its prompt comes from the parent at spawn time, and the run-wide settings you approve (model, harness, and where the children run) apply to every child in the batch.
+
+To give a child a reusable role, put the role's instructions in a [skill](/agents/capabilities/skills/) and ask the parent to have the child use it, for example "spawn one child per package and have each one use the `migrate-tests` skill." A local child starts in the parent's working directory, so it discovers the same repository and home-directory skills as the parent. For a cloud child, the parent attaches the skill when it spawns the child, from a repository in the child's [environment](/platform/environments/).
+
+Named agents with their own standing configuration (instructions, model, harness, secrets, and MCP servers) are part of [Warp Factories](/factories/): a factory's foreman dispatches its [factory agents](/factories/factory-agents/) by name. Outside a factory, every child runs as the user or cloud agent that started the parent.
+
 ## Run state transitions
 
 Each run progresses through a small set of states. The parent observes these transitions to decide what to do next - keep waiting, send a follow-up, spawn a replacement, or finish.
@@ -99,7 +107,7 @@ The parent encodes a directed acyclic graph of subtasks where some nodes depend
 
 ### Swarm
 
-A flat group of peer agents discover each other through messaging and coordinate without a strict hierarchy. The parent acts more like a coordinator than a supervisor. Use sparingly - swarms are powerful but harder to debug than hierarchical patterns.
+A flat group of peer agents discover each other through messaging and coordinate without a strict hierarchy. The parent acts more like a coordinator than a supervisor. Use sparingly - swarms are harder to debug than hierarchical patterns.
 
 ## Approval mode