Skip to main content
skill CX Codex official · Anthropic

breakdown-diagnosis — Claude Code skill: what it does, how to install

breakdown-diagnosis — a skill for Claude Code that ranks likely causes for equipment failure. It drafts downtime records and preventive maintenance plans based on maintenance history and sensor data.

Apache-2.0 ★ 47,914 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add anthropics/claude-plugins-official --skill breakdown-diagnosis -a claude-code
Open on GitHub

What breakdown-diagnosis does

The tool processes sensor readings, maintenance logs, technician notes, and manufacturer manuals to identify the root cause of a breakdown. It filters out generic template entries to focus only on evidence specific to the machine. Safety hazards are surfaced and flagged immediately, preceding any diagnostic output.

To function, it requires running plant_setup.py and accessing CMMS data, sensor exports, or Microsoft 365 documentation. It processes CSV files, PDFs, and images provided in the conversation. The skill operates without active sensor connections or specific CMMS integrations, though it relies on uploaded technical documents for analysis.

What it helps with

  • identify likely equipment failure causes
  • analyze maintenance logs and technician notes
  • draft downtime records for production reports
  • update preventive maintenance intervals

Example prompts for the agent

  • Diagnose the machine failure reported in the latest maintenance order
  • Why does this asset keep failing despite regular maintenance?
  • Analyze the sensor logs and suggest the cheapest discriminating test

How to install breakdown-diagnosis

1Skills CLI (Vercel)

npx skills add anthropics/claude-plugins-official --skill breakdown-diagnosis -a claude-code

2Manually: put the files in place

~/.claude/skills/breakdown-diagnosis/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/breakdown-diagnosis/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about breakdown-diagnosis

How to install breakdown-diagnosis in Claude Code?

Run the command npx skills add anthropics/claude-plugins-official --skill breakdown-diagnosis -a claude-code within your project directory.

What does breakdown-diagnosis do?

It ranks potential failure causes by cross-referencing maintenance history, sensor data, and manuals, while ensuring safety implications are addressed first.

What is required for breakdown-diagnosis to work?

You need CMMS integration, historian sensor exports, technical manuals, and technician photos, along with initial configuration via the plant_setup.py script.

Source text

SKILL.md · Apache-2.0
---
name: breakdown-diagnosis
description: "When a machine goes down, reads the sensor window before the failure, the asset's maintenance history including the free-text close-out notes technicians actually wrote, photos of what they can see, and the manufacturer's troubleshooting tree — then ranks likely causes, each with its supporting evidence, the specific prior work orders behind it, and the cheapest test that would tell them apart. Surfaces any safety implication before any diagnosis. Drafts the PM interval change that would stop it recurring, and emits a downtime record for the next production report. Batch mode ranks bad actors across every asset. Use when someone says \"the machine is down,\" \"what's wrong with this machine,\" \"why does this keep failing,\" \"diagnose this,\" or \"which machines are hurting us most.\""
compatibility: "Requires none. Reads a CMMS connector (Limble, added through custom-connector, is the worked example) for assets, maintenance history and PM plans when connected, plus historian sensor exports, photos and manuals from Microsoft 365. Runs usefully with no sensor data and no connector. Output is always a draft the technician applies."
---

# Breakdown Diagnosis

A machine is down. Every minute it stays down, the plant is not producing — and
**the largest component of MTTR is usually not the repair, it is working out what
is wrong.**

The technician has five sources of evidence available and time to assemble none
of them. That gap is this skill.

**Quick start**

```
→ Capture the event: asset, time down, symptom, fault codes
→ SAFETY FIRST: if there is a safety implication, that leads. Always
→ Pull the sensor window; read shapes, not just threshold breaches
→ Mine maintenance history and the free-text close-out notes
→ Read the photos; consult the manual's troubleshooting tree
→ Rank candidate causes: evidence, cheapest discriminating test, expected fix
→ Cite the specific prior work orders behind each candidate
→ Draft the PM interval change that would stop it recurring
→ Emit the downtime record for the next production report
```

---

## Safety leads. Always.

**Where a failure has a safety implication, surface it first — before any
diagnosis.** Never let a diagnostic suggestion precede a safety flag.

**Every diagnosis opens with this line, flagged or not:** *"Follow your plant's
lockout procedure before anyone works on this machine. This is not a safety
assessment."* A false flag never removes it, and no step sends anyone to the
machine above it.

A technician reading a ranked list of likely causes is already reaching for
tools. If the honest answer is "this guard is defeated" or "that is a stored
energy hazard," it has to arrive before the thing that sends them toward the
machine, not underneath it.

This is a done-when condition, and it is the one non-negotiable ordering rule in
the skill.

**What counts as a safety implication.** Set `safety_flagged: true` when the
evidence shows any of these, and write which one, with its evidence, in
`safety_reason`:

- a seized or locked rotating part: spindle, chuck, bar feeder, conveyor
- a defeated, bypassed or failed guard or interlock
- stored energy: springs, counterweights, a part under load, a raised axis
- hydraulic or pneumatic pressure that has to be bled before work
- an electrical fault: a trip, a burnt smell, exposed or damaged wiring
- a fault that was cleared by restarting rather than fixed (*"ran off and
  restarted"*), now repeating

When none of these is shown, the flag is false and `safety_reason` says *"none
of the safety triggers shown"*. Never set the flag on a feeling, and never leave it off
because the diagnosis is uncertain: an uncertain stored-energy hazard is a
safety implication.

---

## Inputs

**First, find the plant setup:** from the task's own folder (never `cd` into the plugin), run
`python3 -I <this skill's folder>/../../shared/scripts/plant_setup.py find`, do its `setup_page_first` step, then read the profile at
`profile_path` and any rate at `rates_path`, per `../../shared/replies.md`.

| Input | Source | Form |
|---|---|---|
| The breakdown event | User report, or a maintenance work order | Conversation / CMMS connector or maintenance export |
| Asset record and specs | CMMS | CMMS connector, else the asset register export |
| Maintenance history and close-out notes | CMMS | CMMS connector, else the maintenance export |
| Current PM plan for the asset | CMMS | CMMS connector |
| Sensor window around the failure | Historian export to M365, scheduled or on-demand | CSV |
| Technician photos | M365, or uploaded in conversation | Images |
| Manufacturer's manual | M365 document library | PDF |
| Production context — what was running | `data-consolidate` output, or a direct MES export | `../../shared/contracts/consolidated-dataset.md` |

---

## Workflow

### Step 1 — Capture the event

Asset, time it went down, the symptom as the technician describes it, and any
fault codes the machine is showing. Take their words; do not translate a symptom
into a cause at capture.

### Step 2 — Pull the sensor window

A configurable period before the failure. **Read excursions, trends and step
changes, not just threshold breaches** — a vibration reading that climbed for six
hours without ever crossing its alarm limit is a bearing failing in plain sight.

Verify the window covers the event. If it does not, say so and do not reason
from adjacent data as if it were the event.

### Step 3 — Mine the maintenance history and close-out notes

Weight recency and symptom similarity. Search this asset, **then siblings of the
same model** — a new machine with no history is not a dead end.

**Run both searches as queries, in code, and keep what they returned.** One
filter on this asset's ID, one across every asset of the same model on the
symptom's own words. The work orders each query returned go into the figures
block (`../../shared/computed-figures.md`) by number. "This asset has eleven
prior records" and "the sister machine has no bearing history" are both claims
about a query result, and both have been wrong when written from memory: a
count is printed from the filter, and an absence names the filter that came
back empty.

**Then run the template check, every time, before any note is cited.** Group
every close-out note in the history by its exact text, and for each group count
the distinct assets and the distinct makes and models it appears on. The model
comes from the asset name where the asset record has no model column, and the
output says so. The grouped result goes in the figures block. Then:

- **Same text on assets of different makes** is a template — a default the
  technician clicked, not an observation about this machine. It is **shown**,
  labelled *"same text on N assets — not specific to this machine"*, may be
  mentioned as a fleet-wide pattern, and is **never cited as this machine's
  evidence** for any candidate.
- **The same failure recurring on siblings of the same model** is exactly what
  the sibling search is for: cite it as a fleet pattern for that model, with
  the work orders named.
- A note that appears once is this asset's evidence, and is cited.

Skipping this check is how two runs on the same data cite two different sets
of work orders. With it, the cited set is a function of the data.

The free-text close-out notes are the highest-value input here and the least used
anywhere. Read `reference/evidence-sources.md` for how to mine them and how to
report their coverage honestly.

### Step 4 — Read the photos

Visible damage, leaks, wear, part numbers on the failed component, readings on
the machine's own display. Describe what is visible; **never assert a diagnosis
from an unclear image.**

### Step 5 — Consult the manual

Match the fault code and symptom to the manufacturer's troubleshooting tree, and
cite the page. A manufacturer's stated tolerance beats an inference.

### Step 6 — Rank candidate causes

Ordered by likelihood. Each one carries three things:

1. **The evidence supporting it**, from the sources above
2. **What to check first** — the cheapest and fastest test that would
   discriminate between this candidate and the next one
3. **The expected fix**, and the repair path

That second item is the one that saves time. Ranking three causes is useful;
naming the five-minute check that eliminates two of them is what shortens MTTR.

**Every candidate is written under the same three sub-headings, in this
order: Evidence / First check / Expected fix and repair path.** Fixed
headings, every candidate, including the leading one. A candidate whose
Expected fix is missing shows an empty heading, which a reader can see; the
rerun found the leading candidate silently lacking one while candidate 2 had
it, and a fixed shape is what stops that.

### Step 7 — Cite the specific prior work orders

Behind each candidate, the actual work order numbers and close-out notes, so the
technician can read what was done last time rather than taking a ranked list on
trust.

**A candidate with no citation is a guess and is labelled as one.** Not omitted —
an experienced hunch is worth stating — but marked as reasoning rather than
evidence.

### Step 8 — Propose the PM plan adjustment

Once a diagnosis lands, the specific interval or procedure change for **that
asset and that failure mode**, drafted for the maintenance planner.

If a bearing failed from misalignment at 1,400 hours, the interval or the
procedure should probably change. This almost never happens today, because the
person diagnosing is not the person who owns the PM schedule. Closing that loop
is the reactive-to-proactive step and it is core behaviour, not an extra.

**Without the current PM plan** this degrades to a recommendation that first asks
what today's interval is. The step stays either way.

**Pricing the stoppage.** Where someone asks what the downtime cost, resolve
the downtime cost per hour per `../../shared/secret-config.md`, *Resolving a
rate* — `MFG_DOWNTIME_COST_PER_HOUR` if set, then a confirmed rate in the plant
profile, then a placeholder there, labelled — multiply hours by it, and show it
as an internal figure with its source. Where neither route holds one, report
minutes and hours, name the rate and both ways to set it, and stop — see Edge
cases. Never reach for an industry figure.

### Step 9 — Batch mode: the bad actor ranking

Run across all assets instead of one incident, ranked by total downtime minutes
**and** by failure frequency. A different question from "what is wrong with this
machine right now," which is why it is a mode here rather than a separate report.

Read `reference/bad-actor-mode.md`.

---

## Approval gates

**Everything this skill produces is a draft the technician or planner applies.**
Nothing is written back to any system of record.

A CMMS connector's write scope is not assumed — Limble's, the worked example,
is not confirmed in its public setup guide — so this is designed for read-only and treats write as an
upgrade rather than an assumption. Concretely:

- **Never update a maintenance ticket automatically.** The diagnosis is output
  the technician applies.
- **Asked to close out or update the ticket, write the close-out note as a
  labelled draft.** Say it never writes to a system of record — and, where
  no CMMS connector is live, say that too — then **produce the note itself**:
  what was found, what was done, what to watch, in the words a technician
  would put in the close-out field. "Paste it into the ticket if it is right"
  with nothing to paste hands the work back. Never offer to close it later.
  Per `../../shared/command-center.md`.
- **The PM adjustment is a draft for the planner**, who owns that schedule.
- **The diagnosis stays advisory** until a technician confirms it. Its downtime
  record carries that state explicitly, so the production report cannot present
  an unconfirmed cause as established.

---

## Output

**Every document this skill produces is printed in the reply, in full.**
Saving a copy to a file as well is fine, as Word or Excel per `../../shared/replies.md`, never `.txt`; a file *instead of* the reply is not.
The person reads the reply, and every delimited block and outbound check lives
in it — a document only on disk has been neither seen nor checked.
**A record handed to another skill is saved and summarised, never pasted as
raw YAML**; memory blocks are written where the plant's memory lives; and the
name on an approval is asked, never taken from the account. All three per
`../../shared/replies.md`.

**Ranked candidate causes** — evidence, what to check first, expected fix,
repair path.

**Cited history** — the specific prior work orders and close-out notes behind
each candidate.

**Sensor observation summary** — what the data showed in the failure window,
plainly stated, including when it showed nothing.

**The figures block** — required whenever the output states a count, a
duration, a ratio or an absence. Every record count, every "N of M notes were
usable," and every "no history found" appears here with the query behind it,
and the prose quotes it. Per `../../shared/computed-figures.md`. An absence
found by a document search is reported as *not found by search*, never as *does
not exist*.

**PM plan adjustment proposal** — drafted for the planner.

**The downtime record** — per `../../shared/contracts/downtime-record.md`, in
exactly the shape `daily-production-report` consumes with no transformation
between. Note in particular that an ongoing outage carries a null duration
rather than zero, and that `safety_flagged` travels with it.

**Bad actor ranking** — in batch mode.

**The Operations command-center page, maintenance section** — the diagnosis
and its current status, produced as an artifact you place. Nothing is written
to a system. Read `../../shared/command-center.md`. Chain 4's other half,
folding the diagnosis into the next production report's downtime log, happens
on `daily-production-report`'s side of the handoff.

Rendered in the house artifact style (`../../shared/artifact-style.md`) when the
output is something the technician will refer back to.

---

## Edge cases and failure modes

- **No sensor data for this asset** — very common; most assets are not
  instrumented. Proceed on history, notes, photos and the manual, and say clearly
  that sensor evidence was unavailable. This is the normal run, not a degraded one.
- **The sensor export does not cover the failure window** — say so. Do not reason
  from adjacent data.
- **A new asset with no history** — fall back to the manual and to sibling assets
  of the same model. State which.
- **Close-out notes are terse or useless** — "fixed," "repaired," "OK now."
  Report the coverage honestly rather than over-reading them.
- **Photos are ambiguous** — describe what is visible and name what cannot be
  told apart from the image.
- **A safety-critical failure** — the safety implication leads, before any
  diagnosis.
- **Evidence supports two candidates equally** — present both. Do not break the
  tie artificially.
- **Asked what the downtime has cost, with no rate on file** — say the rate is
  not set in either route, name `MFG_DOWNTIME_COST_PER_HOUR` and the plant
  profile ("update our downtime cost"), and report the downtime in
  minutes and hours. **No dollar-per-hour figure of any kind appears**: not a
  typical one, not a range, not an example of what *not* to use. A benchmark
  named in order to reject it is still the number that gets used. Per
  `../../shared/secret-config.md`.

---

## Degradation

**If no CMMS connector is live** (the default: Limble and other CMMS
systems are added through `custom-connector`) — this is the skill most affected.
Without Limble or any CMMS connector, it reads the maintenance export.

**What is lost:** live asset records, open maintenance work orders, and the
current PM plan.

**What survives, and it is the important part:** maintenance history including
the free-text close-out notes, because those are a field on the work order record
and export cleanly. The notes are the highest-value input in the skill, so its
core reasoning is intact.

**What actually changes is freshness.** A breakdown is a real-time event and a
nightly export is not. Diagnosing a machine that went down twenty minutes ago
means the most recent — and often most relevant — tickets are not in the data
yet. Say so rather than letting the history look current.

**Three mitigations, all built, because any one recovers most of the value:**

1. An **on-demand export** the technician can trigger before the run.
2. **Pasted or uploaded work orders** for that asset.
3. A **spoken description of recent work** in conversation. "We were in there
   last Tuesday for the same thing" is real evidence.

The PM adjustment step degrades to a recommendation that first asks what the
current interval is. It stays in the skill either way.

---

## Chain position

**Chain 4, Breakdown to next report** — step 1, feeding
`daily-production-report`. The chain pauses at step 4 by nature, because that
step is a human working a physical machine, and the diagnosis is advisory
throughout.

**Metric.** Mean time to repair.

---

## Reference files

| File | Load when |
|---|---|
| `reference/evidence-sources.md` | Steps 2 to 5 — the five sources, how to read each, and the citation rule |
| `reference/bad-actor-mode.md` | Step 9 — the batch ranking and its coverage traps |
| `../../shared/computed-figures.md` | Step 3 and on emit — the figures block, and how to state an absence |
| `../../shared/contracts/downtime-record.md` | On emit — the exact shape `daily-production-report` consumes |

© anthropics · Apache-2.0 · anthropics/claude-plugins-official

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set175

The whole set →
daily-production-report daily-production-report — a skill for Claude Code and Codex that generates daily morning manufacturing reports. Runs before morning production standups using raw MES and ERP data exports. CX Codex +1 ★ 47,914repo stars customer-inquiry-intake The customer-inquiry-intake Claude Code skill turns customer RFQs into a structured intake form. It runs when an inquiry arrives and helps surface gaps before questions go back to the customer. CX Codex +1 ★ 47,914repo stars custom-connector custom-connector — a Claude Code skill for integrating manufacturing ERP systems. It evaluates access methods ranging from vendor MCPs to scheduled data exports to find the optimal connection strategy. CX Codex +1 ★ 47,914repo stars breakdown-to-next-report The breakdown-to-next-report Claude Code skill investigates equipment failures and carries the downtime record into the next production report. It starts from a breakdown or a request to run the diagnostic chain. CX Codex +1 ★ 47,914repo stars routines routines is a Claude Code skill that prepares recurring work for /schedule. It covers PR digests, stale guidance checks, and progress updates. CX Codex +1 ★ 47,914repo stars patterns This skill extracts actionable patterns from repository history and pull requests to streamline team workflows. It identifies recurring tasks and effective practices to formalize as rules or tools. CX Codex +1 ★ 47,914repo stars office-hours This Claude Code skill organizes recurring office hours and drafts an agenda or session notes. It starts when a team wants a regular place to discuss work problems. CX Codex +1 ★ 47,914repo stars maturity Assesses team AI adoption across maturity stages and generates an evidence-backed HTML audit report. CX Codex +1 ★ 47,914repo stars

Project sponsors

Companies that keep this analytics open