Claude Code Sub-Agent Cookbook

A working library of 32 Claude Code sub-agents covering n8n, Obsidian, VS Code, Kali Linux, homelab/Unraid, media production, vehicle diagnostics, and the Claude Code CLI itself — plus two meta-agents that build new sub-agents and new skills for you.

This is the working stack of someone who actually uses Claude Code daily. The agents are real, the orchestrator → specialist pattern is real, and you can drop any subset of them into your own .claude/agents/ directory and they'll auto-discover.

What you're getting

Meta-agents (build new agents)

Agent	What it does
meta/subagent-architect.md	Designs and writes new .claude/agents/*.md files from a task description. Knows orchestrator vs. worker patterns, model selection (Opus/Sonnet/Haiku), tool scoping.
meta/skill-builder.md	Designs and writes new Claude Code skills (/slash-commands). Knows the skill-vs-subagent decision framework.

These two are the most reusable. If you copy nothing else from this repo, copy these.

Domain agents

Each group follows the orchestrator + specialists pattern: one routing agent that dispatches questions, plus N specialists that go deep on one area.

Group	Orchestrator	Specialists
n8n	n8n-orchestrator	n8n-error-analyzer, n8n-workflow-designer, n8n-node-fixer
Obsidian	obsidian-orchestrator	obsidian-summarizer, obsidian-vault-auditor, obsidian-daily-brief
VS Code	vscode-orchestrator	vscode-extension-advisor, vscode-settings-optimizer
Kali / pentest	kali-orchestrator	kali-recon-analyst, kali-report-writer
Homelab	homelab-orchestrator	homelab-service-advisor, homelab-storage-advisor, pc-hardware-advisor
Media production	media-orchestrator	media-camera-advisor, media-encoder
Claude Code itself	claude-code-orchestrator	claude-code-memory-updater, claude-code-settings-advisor
Vehicles (example domain)	auto/auto-orchestrator	auto-general-advisor + per-platform specialists

Why the vehicle agents are included as the headline example

The five vehicle agents in agents/auto/ are the cleanest demonstration of the orchestrator pattern in this repo:

• Generic question (P0420 code) → routes to auto-general-advisor for OBD code lookup
• Platform-specific question (my Suburban grinds shifting into 4WD) → routes to vehicle-gmt900-suburban, which knows the encoder-motor failure mode for that generation specifically
• Cross-platform question (oil consumption — is it normal?) → orchestrator identifies the vehicle from context, then routes appropriately

The pattern transfers directly to any domain where you have multiple things (devices, codebases, customers, suppliers) that share generic-vs-specific knowledge.

Documentation

Doc	What it covers
docs/HOW-TO-BUILD-SUBAGENTS.md	412-line reference on designing sub-agents. Two-pattern comparison (CLAUDE.md project agent vs. .claude/agents/ worker), frontmatter spec, model selection rules, the orchestrator/specialist pattern, examples
docs/HOW-TO-CREATE-SME-AGENT.md	Step-by-step guide for the CLAUDE.md-in-project-folder pattern (different from the worker pattern above)
docs/SME-AGENT-PROMPT.md	The system prompt that turns a Claude Project into an SME — template you can adapt
docs/SME-KNOWLEDGE-BASE.md	1,682-line knowledge base on integrating Claude Code + n8n + Obsidian + VS Code as a coherent stack. Worth reading even if you never build an SME agent.

How to install agents

Sub-agents live at ~/.claude/agents/ (on Linux/macOS) or %USERPROFILE%\.claude\agents\ (Windows). Claude Code auto-discovers any .md file there.

# Install the meta-agents (everyone wants these)
cp agents/meta/*.md ~/.claude/agents/

# Install the n8n stack
cp agents/n8n/*.md ~/.claude/agents/

# Or grab everything
cp -r agents/*/*.md ~/.claude/agents/

That's it. Open any Claude Code session and the agents are usable immediately — no restart, no config.

How an agent file is structured

---
name: my-agent
description: |
  Use this agent when [scenario]. Includes <example> blocks that help
  Claude decide when to dispatch to this agent.
model: sonnet                 # or 'opus' / 'haiku' / 'inherit'
tools:                        # optional — restrict to a subset
  - Read
  - Grep
  - Glob
---

# System prompt for the agent goes here in markdown.
# It can be as long as you want; this is the agent's "memory" for the
# duration of any invocation.

Open any file in agents/ to see real examples. The two meta-agents (subagent-architect.md, skill-builder.md) are extensively commented because their job is to generate more files like themselves.

Orchestrator pattern in one paragraph

An orchestrator is a thin agent whose entire job is to look at a question and hand it to the right specialist agent. The orchestrator doesn't try to answer the question itself. Pattern: user → orchestrator (10 lines of routing logic) → specialist (500 lines of domain expertise) → response. The advantage is that each specialist has a small, sharp system prompt and a focused tool set. The disadvantage is one extra LLM hop. For domains where you already have specialists, the routing saves more tokens than it costs.

Tradeoffs and notes

• The vehicle agents are personalized. They reference specific platforms and builds (a turbo'd LS-swap K1500, a 2007 GMT900 Suburban, etc.). Useful as the template — replace platform details with your own.
• The Kali pentest agents assume authorized targets only. Don't deploy them against systems you don't have written permission to test.
• Some agents reference paths inside the original author's workspace. Sub-agents generally don't read the filesystem unless given Read/Glob tools, so this is cosmetic; replace as needed.
• Model selection matters more than people think. Sonnet is the default for most of these. Opus is reserved for subagent-architect and skill-builder (because designing agents is a judgment task) and for orchestrators when the routing decision is complex. Haiku is for triage/router-only agents.

License

MIT — copy, adapt, build your own library. Attribution appreciated but not required.