What is a subagent in Claude Code?
A subagent is an assistant you hand a side job to. Exactly like telling a junior engineer: "go through this manual and bring me back the failure modes and recommended maintenance — just the useful bits." It does the digging on its own, and hands you back a clean one-page summary.
In Claude's own words: the chat you type into is the main session; a subagent is a separate helper session it starts up, gives one task, and collects a report from. Three things set it apart from doing the job yourself in the chat:
1. A clean desk. It wakes up blank — it sees only the task you hand it, not your three hours of back-and-forth. 2. Its own engine. It can run a smaller, cheaper model (Haiku) while your main session keeps the top one. 3. One-way reporting. It does the job, hands you a short summary, and disappears. The 300 pages it read stay on its desk, never piling onto yours.
The 300-page PDF gets read in the subagent's own session. Your chat receives one page of structured findings — not the 300 pages.
Paste the 300-page manual.
Claude reads it — and that pile now sits in your context forever. It burns your context window and dilutes every answer that follows, because the signal you care about is drowning in raw material you'll never need again.
"Go read it. Report back."
The agent reads the pile in its own fresh session and sends back one page of synthesis. The tokens it burned never touch your chat. Your main session stays sharp for the judgment calls.
Why this matters more in reliability than almost anywhere.
Reliability data is heavy: a CMMS export runs 10,000+ rows, an OEM manual hundreds of pages. The AI works on a kind of desk — its working memory — and like any desk it only holds so much. Pile raw data onto it and the answers get vaguer, because the one detail that matters is buried under stuff it'll never need again. The test for when to hand the reading to a subagent instead:
The test. "Is this task about to dump a pile of stuff into my chat that I'll never read again?" If yes → subagent. Work order dumps, OEM manuals, vibration report archives, old RCA files: delegate the reading, keep the synthesis.
The distinction that confuses everyone
Skills vs. subagents.
Both are plain text files that hand Claude a ready-made way of working — so what tells them apart? It comes down to where the work happens. A skill is a method Claude follows right beside you, inside your conversation — like a colleague at the same desk, seeing everything you see and going back and forth with you. A subagent is a job you send out of the room — the helper works on its own, sees only the task you handed it, and comes back with the finished result. (New to skills? Start with 18 Reliability Skills for Claude — the methods this team executes.)
| Skill | Subagent | |
|---|---|---|
| Runs in | Your main session | Its own fresh session |
| Context | Shares yours — sees the conversation | Blank — sees only its task prompt |
| Model | Yours | Its own (can be cheaper) |
| Parallelism | No | Yes — run many at once |
| Token cost lands in | Your main context | Isolated — only the report comes back |
So your Weibull skill belongs in the main session — you work with it, discussing beta values and intervals together. Your manual-reader belongs in a subagent — a self-contained job whose raw material you never want in your chat.
And they work together: a skill can send out subagents. An "FMECA prep" skill might fire off a manual-reader and a cmms-digester at the same time, then assemble their reports into a ready-made worksheet. They're not rivals — they're layers.
Built-in · zero setup
General-purpose subagents
Exist out of the box. Say "spin up five subagents — an operator, a planner, a maintenance tech, an HSE advisor, a cost controller — and have each review this draft PM program" and Claude Code prompts five generic agents differently. Powerful, instant — but nothing is saved. Tomorrow you'd re-describe all five personas.
Custom · this page
Your own specialists
Each is a single markdown file in .claude/agents/. Versionable in your repo, shareable with your team: a colleague drops the file into their own folder and immediately has your specialist — same trigger, same rules, same output format, every time.
It's just a text file
What's inside an agent.
Good news first: you won't write any code. An agent is just a plain text file, and it's laid out like a piece of equipment — a nameplate at the top holding the settings, and an instruction sheet underneath telling it how to do the job. Here's a real one, the CMMS digester from the team below.
--- name: cmms-digester description: Use this agent when the user needs to read, clean, or structure raw CMMS work order exports (CSV/Excel). Triggers on phrases like "digest this export", "structure these work orders", "clean this CMMS data". Returns structured failure histories per equipment tag using the site failure code taxonomy. model: haiku tools: read-only color: blue --- You are a CMMS data specialist. When given a raw work order export: 1. Group records by equipment tag (functional location) 2. Map free-text descriptions to the site failure code taxonomy defined in the project CLAUDE.md 3. Flag records that cannot be confidently classified — never guess 4. Return a structured summary per tag: failure modes observed, frequencies, dates, and trends 5. Keep the output under 2 pages. Raw data stays with you.
The nameplate is the block at the very top, fenced by the two --- lines. (Its official name is the YAML front matter — but all that means is "a handful of settings, written one per line.") Four of them matter: name — what you call it. description — when it should wake up (the part most people get wrong, more below). model — which engine it runs on; haiku here, because sorting work orders is high-volume grunt work, not judgement. tools — read-only, so it can look but never touch.
One practical warning. That settings block is fussy about punctuation: open a quote mark and forget to close it, and the whole agent quietly breaks — it simply never shows up, with no error and no warning. So if an agent mysteriously won't trigger, check the punctuation at the top of the file first.
The description is what wakes it up.
Claude Code doesn't read all seven agents in full every time you type — that would be wasteful and slow. It skims just the name and one-line description of each, like glancing down a list of job titles, and only opens the full instructions for the one that fits the task at hand. Two things follow from that.
First, the description does all the triggering work. A vague description ("helps with maintenance data") gets ignored or misfires. A precise one names the situations and the trigger phrases: "Use when the user asks to challenge, stress-test, or 'red-team' an RCA. Triggers on 'challenge my RCA', 'attack this root cause', 'find the holes'." Keep it tight — a paragraph-long description defeats the purpose.
Second, expect to iterate. When an agent doesn't fire and you think it should have, ask Claude Code directly: "You didn't invoke the rca-challenger agent on my last prompt. Read its description, read my prompt, and tell me why — then fix the description." It will diagnose its own triggering logic. Nobody writes a perfect description on the first try.
For reliability & maintenance engineers
Meet the team: 7 specialists, 1 workflow.
Not a catalog — a crew. Two cheap readers feed the data, three analysts turn it into findings, one writer takes it to the field, and one adversary attacks your conclusions before management does. Every agent is read-only by configuration.
1 · Feed
Digest the raw piles
oem-manual-extractor
cmms-digester
2 · Analyse
Turn data into findings
weibull-analyst
fmeca-drafter
bad-actor-hunter
3 · Produce
Take it to the field
pmi-builder
4 · Challenge
Attack the conclusions
rca-challenger
The manual reader
Reads a 300-page OEM manual in isolation and returns only the reliability-relevant content — failure modes, recommended tasks with frequencies, stated MTBF figures, operating limits, critical spares — every item cited to its page. The perfect illustration of why subagents exist.
"What does the OEM say about the P-3501 seal system?"
Feeds every analysis downstream — FMECA, strategy, spares.
The export digester
Turns a raw work order export — thousands of rows of free text — into structured failure histories per equipment tag, mapped to your site failure-code taxonomy. Flags what it can't classify; never guesses. The job nobody wants and every analysis needs.
"Digest this 5-year export and structure it by tag."
The gateway to the Bad Actor Diagnostic and Maintenance Strategy Optimization.
The life-data interpreter
Fits your failure data and reads beta and eta in engineering language — infant mortality, random, wear-out — then translates into what it means for the PM interval. Says "insufficient data" out loud instead of faking precision.
"Fit this failure data — what does the beta mean?"
At plant scale → Maintenance Strategy Optimization.
The worksheet pre-populator
Arrives at the facilitation session with the FMECA worksheet at 60% — functions, functional failures, modes, effects, every row provenance-tagged. It never scores criticality: rating belongs to the room, with the people who run the equipment.
"Pre-populate the FMECA worksheet for the export compressor."
At plant scale → FMECA inside Maintenance Strategy Optimization.
The worst-offender ranker
Sweeps a structured failure history and ranks the worst contributors by cost, downtime and frequency — ranking logic explicit, counterintuitive signals surfaced. The most-repaired asset isn't always the most expensive one.
"What's killing our availability? Rank the bad actors."
At plant scale → Bad Actor Diagnostic.
The procedure writer
Turns a strategy line or manual extract into a field-ready PM instruction — steps, tools, safety/LOTO, acceptance criteria, duration. Written for the technician on shift, not the auditor. Flags every unsourced value instead of inventing a torque figure.
"Build the PMI for the quarterly seal inspection."
At plant scale → PM Generation.
The adversary — quality control for the whole team
The peer review nobody has time for. Hand it a draft RCA and it must NOT agree with you: it attacks the causal chain link by link, lists alternative causes the investigation didn't rule out, flags missing evidence, challenges where the chain stops — and returns a defensibility verdict before your findings reach management, the insurer, or the regulator. Configure its memory to none, deliberately: a challenger with no memory of your investigation history can't inherit your confirmation bias. The blank context is what makes the critique honest.
"Challenge my RCA — find the holes before the insurer does."
At plant scale → RCA inside Maintenance Strategy Optimization.
Setup guide
Four steps. Two minutes. Claude Code in your project folder.
Download the agents
Go to GitHub → github.com/Rob-Reliability/agents-for-claude, then click Code → Download ZIP.
Prefer one click? Download the ZIP directly. And since any agent file from the internet deserves scrutiny (see governance below): the files are short — read them before installing. That's the point.
Copy them into .claude/agents/
Drop the .md files into the .claude/agents/ folder inside your Claude Code project (create it if it doesn't exist). That's the whole install — they're just markdown files, versionable in your repo and shareable with your team.
your-reliability-project/ ├── CLAUDE.md ← your site context (step 4) ├── .claude/ │ └── agents/ │ ├── oem-manual-extractor.md │ ├── cmms-digester.md │ ├── weibull-analyst.md │ ├── fmeca-drafter.md │ ├── bad-actor-hunter.md │ ├── pmi-builder.md │ └── rca-challenger.md └── data/ ← your exports, manuals, RCAs…
Check them with /agents
Type /agents in Claude Code. You'll see the seven agents, can inspect each one, and can adjust three settings per agent: tools (keep read-only), model (Haiku for the readers, Sonnet for the analysts — already set), and memory.
Memory is the one to get right: give every agent project memory so it inherits your site context — except the rca-challenger, which you set to none on purpose. A challenger with no memory of your investigation history can't inherit your confirmation bias.
You can also build your own from here: choose "Generate with Claude", describe the job and the trigger phrases, and trim the description it writes — it tends to be too long.
Ground them in your site — then prompt
This is the difference between plausible generic output and something your site can actually use. Project-level agents inherit your project's CLAUDE.md — so put your operating context there, once:
- Failure code taxonomy — so the digester classifies against your codes, not generic ones.
- Tag & functional location conventions — so every report speaks your register.
- Criticality matrix & severity scales — referenced by the FMECA drafter (without applying them).
- CMMS in use and its export quirks — column meanings, date formats, known data issues.
- Site terminology — the words your technicians actually use.
The agents are reusable; the site context is what grounds them. New site → new project folder, new CLAUDE.md — same agents. Then just describe the task (the descriptions trigger the right agent) or name it explicitly:
Cheap workers, one smart lead
The economics — and the governance.
Think of it like a crew: you don't put your most expensive engineer on data entry. Run your main session on your best, smartest model — and send the volume work to cheap Haiku subagents.
Reading 12,000 work orders doesn't need your most powerful model. Neither does pulling maintenance tasks out of a manual, or skimming fifty old RCA reports to spot recurring causes. Send those to Haiku agents; keep your top model for the judgment calls — failure mode reasoning, interval decisions, criticality trade-offs. One smart lead, many cheap specialists: faster, and far cheaper than running everything through your premium model.
And the smarter the lead, the more this pays off. Claude Fable 5 (released June 9, 2026, Anthropic's most capable tier, a notch above Opus 4.8) is roughly twice the price of Opus to run. At that rate, putting your top model on transcription work isn't just clumsy — it's a line on the budget. Hand the reading to the cheap workers; save the expensive brain for the decisions.
The governance rule. "If your AI can touch data, assume it will." Typing "please don't change these files" into a prompt is asking nicely — the AI can still ignore it. Setting tools: read-only on the agent's nameplate is a lock on the door. Only the second one actually holds.
For anything touching CMMS data, safety-critical procedures, or the asset register: build agents read-only by default and grant write access only where the job requires it. All seven agents on this page ship read-only. This is also your answer when IT security asks how the AI is constrained — not "we told it to behave," but "here is the explicit tool allowlist, per agent, in version control."
The same caution applies to any agent you download — including these. A text file off the internet can hide instructions that quietly hijack the agent into doing something you never asked for. So read it before you install it. These files are deliberately short and in plain English; you can read the whole team in ten minutes. (You can even set up a read-only agent whose only job is to check downloaded agent files for anything fishy.)
When to use a subagent — and when not to.
Don't force it. The overhead is real, and some jobs genuinely belong in your main session.
Use one when
- You're about to read a lot of files — manuals, exports, report archives.
- The output will be a wall of text you'll only skim once.
- It's a job you repeat weekly → build a custom agent for it.
- The work splits into independent parallel pieces — 200 PM procedures don't need to be reviewed in sequence.
- You want an unbiased reviewer — fresh context, no memory, honest critique.
Skip it when
- It's a quick edit or single question — the overhead isn't worth it.
- Steps depend on each other — a live RCA where each answer shapes the next question belongs in one continuous session.
- The task needs your full conversation context — subagents wake up blank by design.
- The agent would need to ask you questions — subagents report back; they don't interview you.
- Agents would need to talk to each other — subagents are strictly one-to-one with the main session. Five in parallel cannot coordinate.
A final note on dynamic workflows (introduced with Opus 4.8): for big jobs, Claude Code can spin up dozens of subagents at once under a generated workflow. Impressive — and capable of eating your session limits at frightening speed. Useful for genuinely massive parallel jobs (every PM in a system reviewed at once); overkill for everything else.
Take the team with you
That's the whole team. It's free on GitHub: github.com/Rob-Reliability/agents-for-claude — click Code → Download ZIP, or download directly. Start with one: the job your team repeats every week that nobody enjoys. For most maintenance organizations that's digesting CMMS exports — build that habit first, then add the next agent.
The agents pair with the 18 reliability skills for Claude — the skills are the methods, the agents are the team that executes them in parallel, in clean context, at the right cost. They compose: same ecosystem, two layers. Star or watch the repo to stay on the latest version, and if you see something that could be sharper, I'd genuinely like to hear it.
And if you'd rather have this whole workflow wired into your CMMS, your standards and your templates — running on your data at plant scale - that's literally my day job. Book a 30-minute call, or just email me at hello@robreliability.com and tell me what's eating your team's week.
Hope this helps 🙂 Feel free to reach out if you need anything.
Want this running on your site, done for you?
The same team, run at plant scale on your CMMS data by the people who built it. Start with the Bad Actor Diagnostic – top 10 value destroyers, root causes, costed action plan, in 3–4 weeks. From $7,000.