What is a subagent in Claude Code?
A subagent is a subject-matter expert (SME) you configure once - a focused AI assistant with a single speciality, its own instructions, and its own clean workspace, that Claude Code hands a job to whenever the task fits. Think of shipping an oil sample to the analysis lab: you don't run the spectrometry on your own bench - you send the messy work out, the lab runs it in their own facility, and you get back a one-page report with just the verdict. A Claude Code subagent works the same way: you hand it a self-contained job, it does the heavy reading in its own separate workspace, and it hands back only the conclusions - never the raw pile.
For Claude's official definition, see Create custom subagents in the Claude Code docs.
What makes it different from doing it yourself
The chat you type into is your main session. A subagent is a separate helper session Claude Code spins up, gives one task, and collects a report from. Three things set it apart:
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 real reason they exist
It keeps your context clean
Do it yourself
Send a subagent
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 vs. subagent
It comes down to where the work happens
Skill - in the room
Shares your context. Same desk.
Subagent - sent out
Sees only its task. Returns a result.
| 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-analyzer at the same time, then assemble their reports into a ready-made worksheet. They're not rivals - they're layers.
Subject-matter expertise
Each one is a specialist
oem-manual-extractor
reads the manuals
weibull-analyst
reads the life data
bad-actor-hunter
ranks worst offenders
rca-challenger
attacks your root cause
One agent doing one thing really well beats one agent doing everything okay. So you split the work across specialists - each with its own narrow brief.
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 analyzer from the team below.
The settings block at the top is where you tell Claude Code what this agent is and when to use it. It's only a few short lines - you fill in four things:
name- what you call the agent. Here,cmms-analyzer.description- the job it's for, and the moment it should step in. This is the one that matters most: it's how Claude Code decides whether to hand it the task (more on that just below).model- which engine it runs on. Match it to the job: a small, fast one (haiku) for high-volume grunt work, a bigger one when the task needs real judgement. This analyzer reads and reasons over your data, so it runs onopus(Opus 4.8).tools- what it's allowed to do. You list the exact tools it gets - hereRead, Grep, Glob- so the agent can look at your data but has no write, edit, or shell tool to change it with.
Everything below that block is the instruction sheet - plain directions, in normal English, for how to do the job. No code, just clear writing.
The description is what wakes it up.
Claude Code doesn't read all seven agents every time you type - it skims just each one's name and one-line description, like glancing down a list of job titles, and opens only the one that fits. So the description does all the triggering work.
Make it precise. A vague line ("helps with maintenance data") misfires; a good one names the situations and the trigger phrases: "Use when the user asks to challenge, stress-test, or 'red-team' an RCA - 'challenge my RCA', 'attack this root cause', 'find the holes'." And expect to iterate: when an agent won't fire, just ask Claude Code "why didn't you invoke rca-challenger? Read its description and my prompt, then fix it." - it'll diagnose its own triggering. Nobody nails the description first try.
For reliability & maintenance engineers
Meet the Reliability Crew
Here are the seven subject-matter experts I built for reliability engineering and industrial maintenance - what I've come to call my reliability crew. It's a first cut, not the final word: there could be more, and you'll probably build your own, but these are the ones I've found genuinely useful in the field. Every one is read-only by configuration - they read and reason, never touch your systems.
1 · Feed
Digest the raw piles
oem-manual-extractor
cmms-analyzer
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
oem-manual-extractorHaikuRead-onlyThe 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.
cmms-analyzerOpus 4.8Read-onlyThe CMMS analyzer
Reads a raw work-order export - thousands of rows of free text - and turns it into a structured failure history per equipment tag, mapped to your site failure-code taxonomy. Then surfaces what matters: recurring modes, failure hotspots, the bad actors to dig into, and where your strategy may need a second look. Flags what it can't classify; never guesses - it's only as good as the data you feed it.
"Analyze this 5-year export - what's failing, where, and what should I look at?"
The gateway to the Bad Actor Diagnostic and Maintenance Strategy Optimization.
weibull-analystSonnetRead-onlyThe 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.
fmeca-drafterSonnetRead-onlyThe 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.
bad-actor-hunterSonnetRead-onlyThe 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.
pmi-builderOpus 4.8Read-onlyThe 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.
rca-challengerSonnetRead-onlyThe 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. Five minutes. Claude on the web.
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.
Create a Claude Project
Go to claude.ai → open Projects → create one, e.g. Reliability Co-pilot.
Claude Code? Put the files in your .claude/agents/ folder and skip steps 2–3.
Upload the agents
Add files → Upload from device, then pick the agent .md files you downloaded from the GitHub repo.
GitHub connected? You can add the agents straight from the repository via Add files → GitHub.
Prompt and call the agent
Start your message by naming the agent you want, then paste in everything you've got on the asset. The agent structures the work — but it can only work with what you give it, so the more context, the better.
The most useful things to drop in:
- Asset identity — tag, type and duty (e.g. P-101, centrifugal boiler-feed pump).
- The failure or symptom — what happened, when, and how often.
- Work-order & maintenance history — repairs, parts replaced, costs, downtime.
- Condition-monitoring logs — vibration, oil analysis, thermography trends.
- Operating context & run hours — duty cycle, load, environment.
- Standards & constraints — anything that applies on your site.
Don't worry about formatting — paste raw exports, tables or notes and let Claude make sense of them. The more data, history and logs you give, the sharper the output. Quality in, quality out.
A few examples:
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. Your best model - Opus 4.8, Anthropic's top tier - bills the same on every token, whether it's untangling a failure mode or just reading rows off an export. Putting it 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.
Right-size the engine
Save money: match the model to the job
The trap
A subagent starts blank and re-gathers context. Worth it for a 300-page manual - wasteful for a one-line lookup.
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 an explicit tool allowlist on the agent's nameplate - tools: Read, Grep, Glob, with no write, edit, or shell tool on it - 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.)
And before any of this touches real data: make sure you're cleared to use it. Check that your organization actually allows AI tools on CMMS exports, asset data and safety-critical procedures - many sites have a data-handling or AI policy, and some information simply can't leave the building. Loop in IT and security early rather than asking forgiveness later. The read-only allowlist above is there to make that conversation easy - but it's no substitute for a clear green light from the people who own the data.
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.