We have no user-facing documentation on authoring custom subagents in ~/.netclaw/agents/*.md. The only mention on the site is a single line in src/content/docs/architecture/overview.md, and that line is also stale (it says "Max 10 tool iterations per subagent" — the budget is 30 as of netclaw-dev/netclaw#1236).
Add a guide
New page: src/content/docs/skills/custom-subagents.md (recommended — it sits next to the existing metadata.subagent routing docs in skills/overview.md; configuration/subagents.md is a reasonable alternative).
Frontmatter follows the existing convention (title + description), e.g.:
---
title: "Custom Subagents"
description: "Define your own delegated-work subagents in ~/.netclaw/agents."
---
Wire it into the sidebar: the sidebar in astro.config.mjs is maintained by hand (not autogenerate), so add an entry to the Skills group's items:
{ label: 'Custom Subagents', slug: 'skills/custom-subagents' },Content to cover:
- File location & format — markdown files in
~/.netclaw/agents/*.md; YAML frontmatter + a markdown body that becomes the subagent's system prompt verbatim.
- Frontmatter reference:
name, description — requiredtools — advisory only (runtime tool access comes from the parent session's audience policy, not this list)modelRole — Main or CompactiontimeoutSeconds — inter-delta inactivity budget (max gap between streaming deltas / general tool-loop inactivity)prefillTimeoutSeconds — generous wait-for-first-token budget covering queue wait and cold prefill (new)emitStructuredFindings, visibility (user-facing / internal)
- The two-phase timeout model (prefill vs inter-delta) so operators know how to tune slow / large-context self-hosted backends.
- A worked example.
- Fail-loud loader behavior — invalid files (bad frontmatter, missing required fields, out-of-range timeouts) are skipped with a warning rather than silently served stale.
- Relationship to
metadata.subagent skill routing — cross-link skills/overview.md (slug /skills/overview/).
Also fix the stale line
src/content/docs/architecture/overview.md — change "Max 10 tool iterations per subagent" → 30.
Source to adapt
The agent-facing version of this content already exists in the product repo at netclaw-dev/netclaw → feeds/skills/.system/files/subagent-authoring/SKILL.md (frontmatter table, examples, and loader behavior are all there). The user-facing guide can be adapted from it.
We have no user-facing documentation on authoring custom subagents in
~/.netclaw/agents/*.md. The only mention on the site is a single line insrc/content/docs/architecture/overview.md, and that line is also stale (it says "Max 10 tool iterations per subagent" — the budget is 30 as of netclaw-dev/netclaw#1236).Add a guide
New page:
src/content/docs/skills/custom-subagents.md(recommended — it sits next to the existingmetadata.subagentrouting docs inskills/overview.md;configuration/subagents.mdis a reasonable alternative).Frontmatter follows the existing convention (
title+description), e.g.:Wire it into the sidebar: the sidebar in
astro.config.mjsis maintained by hand (notautogenerate), so add an entry to the Skills group'sitems:Content to cover:
~/.netclaw/agents/*.md; YAML frontmatter + a markdown body that becomes the subagent's system prompt verbatim.name,description— requiredtools— advisory only (runtime tool access comes from the parent session's audience policy, not this list)modelRole—MainorCompactiontimeoutSeconds— inter-delta inactivity budget (max gap between streaming deltas / general tool-loop inactivity)prefillTimeoutSeconds— generous wait-for-first-token budget covering queue wait and cold prefill (new)emitStructuredFindings,visibility(user-facing/internal)metadata.subagentskill routing — cross-linkskills/overview.md(slug/skills/overview/).Also fix the stale line
src/content/docs/architecture/overview.md— change "Max 10 tool iterations per subagent" → 30.Source to adapt
The agent-facing version of this content already exists in the product repo at
netclaw-dev/netclaw→feeds/skills/.system/files/subagent-authoring/SKILL.md(frontmatter table, examples, and loader behavior are all there). The user-facing guide can be adapted from it.