bg-agent
Manage background subagents with tier-routed models, stripped tool contexts, lifecycle pruning, and zero-polling reactive execution to minimize token and credit usage.
SKILL.mdskills/bg-agent/SKILL.md
GitHubbg-agent | Background Agent & Usage Optimization Manager
Orchestrates background agents and subagents with strict usage-saving constraints: tier-routed models (flash_lite default for research), tool-context stripping (no MCP/write bloat), zero-polling event-driven resumption, and active lifecycle pruning.
When to Use
- You want to run tasks in the background without burning high-tier model quota or tokens.
- Decomposing research, file auditing, or discovery across parallel lightweight workers.
- Checking status of running background agents or killing idle/stalled subagents.
- Offloading heavy scripts or command outputs to background tasks to keep context small.
The Usage-Saving Matrix
| Strategy | Mechanism | Usage Impact |
|---|---|---|
| Tier Routing | Dispatch with Model: 'flash_lite' or 'flash' rather than 'inherit' / 'pro' |
80–95% cost reduction per run |
| Tool Scoping | Use TypeName: 'research' or custom define_subagent without MCP or write tools |
Eliminates 1,000s of tokens of schema injection per turn |
| Zero-Polling | Rely on native reactive wakeup; never loop manage_subagents(status) |
Zero wasted API turns while waiting |
| Output Budget | Enforce 300 words max + tool receipts in prompt | Prevents context bloat in parent context |
| Lifecycle Pruning | Call manage_subagents(Action: 'kill') as soon as subagent is idle |
Frees memory & sandboxes, prevents stray notifications |
| Task Offload | Use run_command with WaitMsBeforeAsync for shell scripts/tests |
Prevents stdout spam from poisoning the LLM context |
Subcommands & Usage
1. Launch a Lean Background Subagent
[bg-agent] "Scan all files in src/ for deprecated API usages" --tier flash_lite --type research
Execution Rules:
- Select lowest capable model tier (
flash_lite>flash>pro). - Use
researchtype for read-only tasks (strips write & MCP tools). - Inject the Output Contract: 300 words max, lead with conclusions, raw tool receipts.
- Dispatch via
invoke_subagent. - DO NOT POLL. Stop tool calls and let reactive wakeup deliver the response.
2. Inspect Active Background Subagents
[bg-agent] list
Execution Rules:
- Calls
manage_subagents(Action: 'list'). - Displays table of active subagents:
conversationId,role,type,state(running,idle,waiting_for_input), and transcript URI.
3. Harvest & Terminate (Read-Before-Kill)
[bg-agent] kill <conversation_id>
[bg-agent] kill all
[bg-agent] clean
Execution Rules:
- If cleaning up, check subagent transcript or output first (harvest-before-kill invariant).
- Terminate via
manage_subagents(Action: 'kill', ConversationIds: [...])orAction: 'kill_all'. - Report killed IDs and freed roles.
4. Dynamically Define a Custom Micro-Agent
[bg-agent] define <name> --prompt "<system_prompt>" [--read-only]
Execution Rules:
- Call
define_subagentwith:enable_mcp_tools: falseenable_write_tools: false(unless explicitly requested)enable_subagent_tools: false(enforce leaf execution, prevents recursion)- Minimal system prompt under 100 words.
Output Contract (Mandatory Prompt Injection)
Every prompt dispatched through bg-agent MUST append:
RETURN_FORMAT:
- Max 300 words.
- Lead with actionable conclusions.
- Include tool receipts (file paths, line counts, grepped patterns).
- Do not include narrative filler or internal chain-of-thought.
Constraints & Fleet Invariants
- Concurrency Cap: Maximum 3 concurrent background subagents (per
subagent-quota-discipline.md). - Complexity Gate: Do not spawn a subagent for a single-file grep or read; do it directly.
- Harvest First: Never kill a subagent before its output has arrived or been inspected (per
background-subagent-policy.md). - Depth Bound: Subagents cannot spawn subagents (
enable_subagent_tools: false).