Skip to content

Document defining custom subagents (and fix stale "Max 10 tool iterations") #44

@Aaronontheweb

Description

@Aaronontheweb

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 — required
    • tools — advisory only (runtime tool access comes from the parent session's audience policy, not this list)
    • modelRoleMain or Compaction
    • timeoutSeconds — 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/netclawfeeds/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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions