What is a Claude Code subagent?

A subagent is a specialized instance of Claude Code launched by a parent agent to perform a specific, isolated task independently within its own context window.

How does the two-stage planning process work?

It first generates brief high-level outlines for approach selection (Stage 1), followed by a detailed PLAN.md once an approach is chosen (Stage 2), significantly optimizing token efficiency.

How does this skill handle concurrent tasks?

It uses a mandatory task-level locking mechanism in the .claude/cat/locks/ directory to ensure only one agent session owns a specific task at any given time.

Can I see what a subagent is doing in real-time?

No, subagents run unsupervised without real-time output. All critical decisions and requirement clarifications must be handled by the main agent before spawning.

Why is token tracking required for subagents?

Since subagents run independently, token tracking ensures the main agent can report the total cumulative cost and usage of the entire task in the final STATE.md and completion logs.

Subagent Spawner

Name: Subagent Spawner
Author: cowwoc

bycowwoc

•

Productivity & Workflow

Orchestrates autonomous Claude Code subagents in isolated git worktrees for parallel task execution and context management.

The spawn-subagent skill enables the main Claude Code agent to delegate complex, well-defined tasks to independent subagents. By operating in isolated git worktrees, these subagents can execute implementation or research tasks without cluttering the main agent's context window. It features rigorous token tracking, concurrent execution safety through task-level locking, and a two-stage planning process—separating high-level architectural outlines from detailed implementation specifications—to ensure maximum efficiency and reliability during unsupervised execution.

Key Features

01Two-Stage Planning: Optimizes token usage by separating high-level outlines from detailed implementation specs.

02Concurrent Safety: Implements mandatory task-level locking to prevent multiple agents from conflicting on the same task.

03Fail-Fast Logic: Ensures subagents stop and report status immediately when encountering ambiguities or blockers.

04Isolated Git Worktrees: Runs tasks in separate environments to prevent context pollution and enable parallel work.

05Token Usage Tracking: Automatically measures and reports cumulative token consumption across subagent sessions.

0656 GitHub stars

Use Cases

01Automating mechanical code updates and migrations that follow a predefined PLAN.md with zero-decision delegation.

02Parallelizing independent feature implementations across multiple git worktrees to increase development velocity.

03Conducting deep code exploration or research without exhausting the main agent's context window.

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add cowwoc/cat spawn-subagent

For use in Claude.ai and ChatGPT

Download Skill