NetFabric/NetFabric.Numerics / .agents/skills/claude-code-custom-agents
claude-code-custom-agents
VerifiedCreate and maintain Claude Code custom subagents (.claude/agents/*.md files). USE FOR: authoring project (.claude/agents/) or user (~/.claude/agents/) subagent files; frontmatter fields (name, description, tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, color, initialPrompt); writing descriptions that drive automatic delegation and 'use proactively' phrasing; invoking subagents via natural language, @-mention, session-wide --agent, or the Agent tool; restricting which subagent types a coordinator can spawn with Agent(name1, name2); nested subagents and depth limits; built-in subagents (Explore, Plan, general-purpose, claude); troubleshooting a subagent that won't load or isn't invoked. DO NOT USE FOR: GitHub Copilot CLI custom agents (use copilot-cli-custom-agents); agent teams/teammates (a different, session-spanning feature); MCP server authoring; SKILL.md authoring (use create-skill).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.1 KB |
| references/authoring-workflow.md | markdown | 3.4 KB |
| references/delegation-and-squads.md | markdown | 3.5 KB |
| references/frontmatter-reference.md | markdown | 5.0 KB |
| references/undocumented-and-gotchas.md | markdown | 3.3 KB |
| references/writing-style.md | markdown | 2.8 KB |
references/delegation-and-squads.md
View on GitHub# Delegation & Squads
## Nested subagents
A subagent can spawn subagents of its own by default, up to 3 layers below the main conversation (`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`, set `1` to disable nesting entirely). At the depth limit, Claude Code withholds the `Agent` tool from every subagent except a [fork](#forks-vs-named-subagents). Nested subagents suit a delegated task that itself splits into parallel subtasks (e.g. a reviewer that dispatches a verifier per finding) so only the top-level summary reaches you.
## Coordinator + specialist pattern
```mermaid
flowchart TD
U[User request] --> C[coordinator subagent]
C -->|Agent tool| S1[worker]
C -->|Agent tool| S2[researcher]
S1 & S2 --> R[Synthesized result]
```
```markdown
---
name: coordinator
description: Coordinates work across specialized agents for multi-step tasks.
tools: Agent(worker, researcher), Read, Bash
---
You coordinate a squad of specialists. For each request, decide which
specialists apply, dispatch each via the Agent tool, then synthesize
their findings into one report.
```
`Agent(worker, researcher)` in `tools` allowlists exactly those two subagent types for this coordinator — any other dispatch request fails and the coordinator sees only the allowed types in its own prompt. Full field mechanics (bare `Agent`, omitting it, and the main-thread-only scope of this syntax) → [frontmatter-reference.md](frontmatter-reference.md#restrict-which-subagents-a-coordinator-can-spawn).
To block specific subagents session-wide instead (for every caller, not just one coordinator), use `permissions.deny: ["Agent(subagent-name)"]` in settings — this is a hard block, unlike the allowlist above which is scoped to one coordinator's own dispatch.
## Concurrency & limits
| Limit | Default | Variable |
| --- | --- | --- |
| Nesting depth | 3 layers below main conversation | `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` |
| Concurrent running subagents | 20 | `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` (exempt when `ultracode` effort is active) |
There is no limit on the total subagents spawned over a session — only how many run at once and how deep they nest.
## Resuming a subagent
A completed subagent keeps its agent ID; Claude uses the `SendMessage` tool with that ID (or name) to resume it with full prior context, rather than starting fresh. A subagent you stopped yourself (`x` in `/tasks`) does not auto-resume from a `SendMessage` — you must type into its transcript first. `SendMessage` verifies the name still refers to the same agent instance before delivering, refusing rather than misdirecting if a newer agent reused the name.
## Forks vs. named subagents
A **fork** (`/subtask`, requires opt-in on older versions) inherits the entire parent conversation instead of starting fresh — same system prompt, tools, model, and prompt cache. Use a fork when a named subagent would need too much re-explained background; use a named subagent for a role with its own stable prompt/tools/model reused across many tasks. Forks can't spawn further forks and skip both subagent tool-filters (full parent tool pool, foreground-or-background rules don't apply the same way).
## Agent teams (out of scope here)
Agent teams are a separate, session-spanning multi-agent feature (teammates that persist and message each other via `SendMessage`/task tools) — distinct from the request-scoped subagents this skill covers. A subagent *definition* can be reused as a teammate's base config, but authoring a team's coordination protocol is not covered by this skill.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |