subagent-authoring

name	subagent-authoring
description	How to create and troubleshoot file-defined subagents in ~/.netclaw/agents. Load when the user asks to add, edit, or debug subagent definitions, or when a skill routes via metadata.subagent.
metadata	{"author":"netclaw","version":"1.4.0"}

Subagent Authoring

Use this skill when you need to create, update, or debug subagent definitions.

Audience and Feature Gating

Subagents are subject to two independent gates:

• Audience gate: Public sessions cannot spawn subagents or see the subagent discovery context layer. spawn_agent returns a generic denial for Public.
• Deployment gate: SubAgents.Enabled in netclaw.json (default true). When false, spawn_agent is hidden from discovery for ALL audiences and the subagent discovery context layer returns empty.

Both gates must pass for subagent features to be available.

Working context

A spawned subagent receives the parent turn's project directory and recent-file snapshot in its initial runtime context. The child tracks its own first-party file reads and edits for the lifetime of the run; it never mutates the parent's durable working context directly. On successful completion Netclaw returns a structured file handoff and merges confirmed child edits into the parent for the next turn. Git changes merely observed in a shared worktree are reported without claiming that the child authored them.

When to use

Load this when the user asks to:

• create a new subagent
• edit advisory tool metadata, timeout, or behavior for an existing subagent
• diagnose why a subagent does not appear in [available-subagents]
• route a slash skill through metadata.subagent

File format and location

Subagents are file-defined in:

~/.netclaw/agents/*.md

Each file is a single markdown document with YAML frontmatter and a markdown body. The body is the subagent system prompt verbatim.

Minimal shape:

---
name: my-agent
description: What this agent does
---

You are a specialist assistant. Your job is to...

With advisory tool metadata for compatibility with other agent systems:

---
name: research-assistant
description: Deep web research with search and citation
tools: [web_search, web_fetch, file_read]
---

You are a research assistant.

Required frontmatter fields

These are required for a file to load:

• name (string, non-empty)
• description (string, non-empty)

The markdown body below the closing --- must also be non-empty.

Optional frontmatter fields and defaults

Field	Default	Notes
tools	[]	Advisory tool metadata retained for file-format compatibility. Netclaw does not use this as a runtime whitelist.
modelRole	Compaction	Main or Compaction (case-insensitive). Invalid values make the file fail loud and skip loading.
timeoutSeconds	60	Inter-delta inactivity budget: the max gap between streaming deltas once the model is responding, and the general tool-loop inactivity budget. The watchdog resets on each progress signal.
prefillTimeoutSeconds	inherits SubAgents.PrefillTimeoutSeconds (1800)	Generous wait-for-first-token budget covering queue wait and cold prefill. Content-free prompt_progress keepalives refresh it, so a slow self-hosted prefill is not mistaken for a hang; the watchdog promotes to timeoutSeconds once the first real token arrives. Raise this for heavyweight agents on slow/large-context models.
visibility	user-facing	Accepts user-facing, UserFacing, internal, or Internal. Invalid values make the file fail loud and skip loading.
emitStructuredFindings	false	When true, successful output is emitted as findings for parent-session review.

Unknown fields are ignored.

Beyond these per-agent budgets, every sub-agent LLM call is also bounded by a config-level no-progress ceiling (SubAgents.NoProgressTimeoutSeconds in netclaw.json, default 1200 = 20 min). Unlike prefillTimeoutSeconds and timeoutSeconds, content-free keepalives never refresh it — only real tokens do — so a backend that heartbeats forever without producing output is killed once it elapses. It is not a per-agent frontmatter field; tune it in netclaw.json.

Example: valid subagent definition

---
name: notion-planner
description: Summarizes local daily planning notes for the parent session
timeoutSeconds: 120
---

You are a planning assistant that reviews daily planning notes.

## Goal

Summarize the latest planning notes and highlight next actions.

## Guidelines

- Use file_read to inspect local planning notes and related reference files
- If a referenced file is missing, report that clearly
- Follow the user's existing plan format and structure

This agent inherits the parent session's audience/profile tool policy. User-facing subagents then apply the static subagent denylist, which blocks recursive delegation through spawn_agent. Frontmatter tools: values are advisory only.

Runtime contract

Subagents run as headless workers on behalf of the parent session:

• do the delegated work as far as possible with the task, context, and tools exposed by the parent audience/profile policy
• do not ask the user clarifying questions or wait for conversational replies
• make reasonable assumptions when safe, and state them in the final output
• if blocked, return a final result describing what was found, what remains, and what decision the parent session needs

Parent-mediated tool approval is still allowed for concrete tool calls when the parent channel supports it. Treat approval as a security gate, not as a dialogue channel.

Subagents share the same tool-loop budget strategy as parent sessions: budget nudges, duplicate-call nudges, and force-no-tools wrap-up. The current subagent budget is 30 tool iterations per run, where one LLM response with any number of parallel tool calls counts as one iteration.

The parent-facing spawn_agent result is an explicit terminal text envelope: agent name, run id, outcome (completed, partial, or failed), optional reason, diagnostics pointer, and a Summary: or Error: section. Structured findings, when enabled, are a separate parent-reviewed memory-candidate path; do not rely on them as the visible result returned to the parent model.

Fail-loud loader behavior

On the next turn or subagent lookup, invalid files are skipped with warnings. Common rejection reasons:

• missing or unparseable YAML frontmatter
• missing required fields (name, description)
• empty markdown body
• duplicate name across files (first file in stable sorted order wins)

If you edit a previously valid file into an invalid state, the runtime drops it from the active subagent catalog on the next reload instead of serving the stale last-known-good definition.

Inherited parent context

Spawned subagents inherit the parent session's session_dir and current project_dir as read-only grounding. The child can use those paths for file resolution and project instruction loading, but it does not mutate the parent session's working context.

Non-.md files in ~/.netclaw/agents are ignored.

Relationship to skill routing (metadata.subagent)

Skills can route execution through a subagent with:

metadata:
  subagent: release-notes

If that target is missing, internal-only, or malformed, activation fails deterministically with no inline fallback. Keep routed skill metadata aligned with real user-facing subagent definitions.

Routed skills go through the same loader + registry contract as explicit spawn_agent: the next routed activation reloads the definition from disk and inherits the parent session's session_dir and project_dir exactly the same way. There is no separate code path for routed execution.

Verification checklist

After creating or editing a subagent file:

1. save the file and trigger the next turn or subagent lookup
2. confirm the agent appears in [available-subagents]
3. run a small spawn_agent task to verify inherited context, tool exposure, and output
4. if missing, check daemon logs for the rejection reason

If the user has no agent files yet, netclaw init seeds starter definitions.