Diagnose · wrg32786 — Claude Code skill: what it does, how to install
Diagnose — a Claude Code skill that traces faults across aigent-OS components and settings. It investigates broken hooks, skill routing failures, and unexpected changes in agent behavior.
MIT ★ 26 updated 2026-11-16
npx skills add wrg32786/aigent-os --skill diagnose -a claude-codeWhat Diagnose does
Diagnose checks seven layers of aigent-OS, from principal settings and vault content to skills, hooks, and the kernel. It frames the symptom, proposes a likely cause, then runs one targeted check to confirm or reject that hypothesis. Fix steps come after verification.
Once a cause is confirmed and the fix works, the result goes into vault/memory/FAILURE_MODES.md; unconfirmed guesses are left out. This logging step is available from version v0.2.2 onward. For installation integrity, the skill uses /system-check; it examines the skill catalog with /skill-audit.
What it helps with
- trace a hook that stopped firing
- find why an expected skill does not run
- investigate incomplete context from
/open - identify which layer changed agent behavior
- record a confirmed cause of failure
Example prompts for the agent
- Find out why the hooks stopped firing after an update.
- Work out why the expected skill is not triggered by my prompts.
- Check why
/openleaves out part of the context.
How to install Diagnose
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill diagnose -a claude-code2Manually: put the files in place
~/.claude/skills/diagnose/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/diagnose/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill diagnose -a codex2Manually: put the files in place
.agents/skills/diagnose/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill diagnose -a cursor2Manually: put the files in place
.cursor/skills/diagnose/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install wrg32786/aigent-os skills/diagnose2Manually: put the files in place
.github/skills/diagnose/SKILL.md1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill diagnose -a gemini-cli2Platform CLI
gemini skills install https://github.com/wrg32786/aigent-os --path skills/diagnoseManually: put the files in place
.devin/skills/diagnose/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill diagnose -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about Diagnose
How do I install Diagnose in Claude Code?
Run npx skills add wrg32786/aigent-os --skill diagnose -a claude-code. The skill file is at ~/.claude/skills/diagnose/SKILL.md.
What does Diagnose do?
It traces a problem through seven aigent-OS layers, tests a likely cause, and gives concrete repair steps after verification.
What happens to a diagnosis result?
A confirmed cause and its fix are recorded in vault/memory/FAILURE_MODES.md. Unverified hypotheses are not added.
Source text
SKILL.md · MIT
---
name: Diagnose
description: "Diagnose kernel, skills, hooks, daemons, vault, doctrine, and principal config. Use when hooks fail, routing breaks, or agent behavior changes."
---
# Diagnose
Most failures in an aigent-OS install aren't bugs in any single component — they're integration failures across layers. `/diagnose` walks the stack with you so you don't have to.
## When to use
- "It used to work, now it doesn't"
- A skill you expect is not being invoked
- `/open` produces incomplete context
- Hooks not firing
- Wikilinks not resolving
- AI behavior changed unexpectedly after an update
- Anything you can't immediately attribute to a single component
## How to execute
### Step 1 — Capture the symptom
Ask the user (or read from their prompt):
- **What were you trying to do?**
- **What happened instead?**
- **What did you expect?**
- **What changed recently?** (git pull, new skill installed, hook edit, kernel update)
Frame the symptom in one sentence. Example: *"/channel-audit used to run when I asked about YouTube performance, now it doesn't."*
### Step 2 — Walk the seven-layer stack
For each layer, ask: could this layer be responsible for the symptom? If yes, run the specific check. If no, move on.
```
LAYER 7 — Principal Configuration
- system/00_identity.md customized?
- system/14_decision_framework.md reflects current priorities?
- vault/projects/ and vault/people/ populated?
Check first if symptom involves AI giving wrong context or missing your situation.
LAYER 6 — Doctrine (vault/concepts/)
- Has a relevant doctrine note been edited recently?
- Are there standing rules that should be firing but aren't?
Check if symptom is about AI behavior changing without you having edited the kernel.
LAYER 5 — Vault Content
- Wikilinks resolve? (run /system-check Tier 4)
- Heat index up to date?
- Memory layer current?
Check if symptom is "AI doesn't know about X" or "/open missed Y."
LAYER 4 — Daemons
- Heat compute daemon ran recently?
- Semantic search index fresh?
Check if symptom is "skills not surfacing" or "search results stale."
LAYER 3 — Hooks
- Settings.json wired?
- Hook scripts executable?
- Hook output going where you expect?
Check if symptom is "automated behavior stopped."
LAYER 2 — Skills
- skill-index.json valid?
- Trigger keywords match the user's actual phrasing? (run /skill-audit Section 3)
- Skill descriptions match what the skill does?
- Skill visible at all? Run /context: a skill whose description was dropped by the listing budget cannot be matched.
Check if symptom is "wrong skill firing" or "no skill firing."
LAYER 1 — Kernel
- All 15 system docs present and unmodified?
- CLAUDE.md loaded?
- Authority matrix consistent with what you've authorized?
Check last — kernel issues are rare but high-blast-radius.
```
### Step 3 — Form a hypothesis
State the most likely layer + the specific issue. Example:
*"Hypothesis: Layer 2 (Skills) — the trigger keywords for /channel-audit don't match the phrasing you've started using. /skill-audit Section 3 will confirm."*
### Step 4 — Verify with one targeted check
Run the specific check that confirms or refutes. Don't fix yet — verify the diagnosis first.
### Step 5 — Recommend a fix
Concrete steps. Not advice ("you should…") — commands ("run /skill-audit then add 'performance check' to .claude/skill-index.json line 47").
## Output format
```
🩺 aigent-OS Diagnose
SYMPTOM
{one-sentence framing}
WHAT CHANGED RECENTLY
{if known}
LAYER WALK
✅ L7 Principal Config — OK
✅ L6 Doctrine — OK
✅ L5 Vault — OK
✅ L4 Daemons — OK
✅ L3 Hooks — OK
⚠️ L2 Skills — POSSIBLE CAUSE
✅ L1 Kernel — OK
HYPOTHESIS
Layer 2 (Skills): trigger keywords for /channel-audit drift from current
phrasing. Confirmed by /skill-audit Section 3.
FIX
1. Add "performance check" and "review channels" to /channel-audit's
description ("Use when ...")
2. Save and re-test the failing prompt
3. If still broken, check the skill appears in /context (listing budget)
```
## Step 6 — Write the outcome to the failure modes corpus (v0.2.2+)
When the diagnosis is verified (the layer + symptom matched the actual cause and the fix worked), append to `vault/memory/FAILURE_MODES.md`:
```markdown
## YYYY-MM-DD — {short symptom name}
**Symptom (verbatim from principal):** "{their own words}"
**Layer responsible:** L{N} ({layer name})
**Specific cause:** {file/line/config that was the actual issue}
**Fix applied:** {what the principal or agent did}
**Time to diagnose:** {minutes from /diagnose start to verified cause}
**Pattern (one line):** {what category of failure this was}
```
Why: a single failure is data; recurring failures are doctrine. The corpus enables Phase 2 promotion of patterns that occur 3+ times to [[Common Failure Modes]] permanent doctrine. Without the corpus, the framework can't harden against the failures it's actually had.
Skip this step if the diagnosis didn't verify — only confirmed causes get written. Hypotheses that didn't pan out aren't useful corpus data.
## Why this skill exists
Without `/diagnose`, a user with a broken install has to either dive into the source or give up. The seven-layer model gives them a structured path through the stack — even if they don't fix it themselves, they end up with a precise enough diagnosis to file a useful issue or ask a useful question.
Over time, the corpus this skill builds turns one-off diagnostics into framework hardening — the failure modes the framework has actually hit become the failure modes future principals can recognize in 30 seconds instead of 30 minutes.
## Anti-patterns this prevents
- "Something's broken" → maintainer asks 5 follow-up questions to figure out what
- User fixes the wrong layer (e.g., editing the kernel when the skill was the issue)
- Frustration from intermittent failures with no obvious cause
- Issues filed without enough information to action
## Connects to
- [`/system-check`](../system-check/SKILL.md) — verifies install integrity
- [`/skill-audit`](../skill-audit/SKILL.md) — checks skill catalog hygiene (Layer 2 deep-dive)
© wrg32786 · MIT · wrg32786/aigent-os
Similar skills
SKILL.md skills catalog →Diagnose by other authors comes first.