LLI Wiki — My Digital Knowledge Base

Specialised sub-agents and an orchestrator with Claude Code: when to delegate, limits and costs

A small team of agents (SQL, PowerShell, Azure, documentation reviewer) and an orchestrator: file format, briefs, parallelism, limits and costs.

A sub-agent is a specialist that Claude Code can delegate a task to. It runs in its own context window, with its own instructions and its own tools, and comes back with a summary. On a DBA repository I use a small team: a SQL expert, a PowerShell expert, an Azure expert, a read-only documentation reviewer, and an orchestrator that routes work between them.

What an agent file looks like

An agent is a Markdown file in .claude/agents/. The frontmatter says who it is and what it may do; the body is its system prompt.

---
name: sql-expert
description: Use for T-SQL work: queries, procedures, DDL, migration scripts, tuning, and placeholder templates read by PowerShell.
tools: Read, Edit, Write, Grep, Glob
model: inherit
---

You are a SQL Server and Azure SQL expert for this repository.

## Standards
Follow rule `sql-script.md`. Do not copy it here.

## Safety
Read-only queries are fine. Never run DDL or DML against production: write the script, stop.

## Output
What was done / files changed / how it was validated.

Three fields matter most:

My team

Agent Writes? Role
sql-expert yes T-SQL, templates, tuning
powershell-expert yes functions, modules, Pester tests, lint
azure-expert yes pipeline YAML, Azure SQL, Batch, identity
docs-expert yes README, changelogs, comments
docs-reviewer no checks docs against the code, confirmed findings only
orchestrator no splits a multi-part request and routes it

Naming convention: <domain>-expert writes, <domain>-reviewer only reads. The word tells you the risk before you invoke it.

When to delegate, and when not to

Delegate when:

Do not delegate when:

How to brief an agent

An agent knows only what you put in the brief. A good one has four parts, which I use as a template:

Task: add a -WhatIf switch to function Remove-Foo in the shared module.
Context: the function is called by two applications; do not change its return contract.
Constraints: follow rule powershell-function; do not commit; do not run any entry script.
Expected outcome: changed files, lint clean, one Pester test.

Give rule names, not rule contents. State what is forbidden. Never put secrets or personal data in a brief.

The orchestrator

The orchestrator has no write tools. It reads the request, picks agents, sequences dependent work (the SQL first, then the PowerShell that consumes it), parallelises independent work, validates what comes back and writes the synthesis. If an agent fails twice, it escalates to me instead of looping.

flowchart TD
    U["Request"] --> O["Orchestrator"]
    O --> Q["sql-expert"]
    O --> P["powershell-expert"]
    O --> Z["azure-expert"]
    Q --> P
    P --> D["docs-expert"]
    D --> R["docs-reviewer : read-only"]
    R --> O
    Z --> O
    O --> S["Summary to the DBA"]

Limits and costs

Lessons learned

Mastodon LLIMastodon SocialFosstodon