Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add wrg32786/aigent-os --skill diagnose -a claude-code
Open on GitHub

What 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 /open leaves out part of the context.

How to install Diagnose

1Skills CLI (Vercel)

npx skills add wrg32786/aigent-os --skill diagnose -a claude-code

2Manually: put the files in place

~/.claude/skills/diagnose/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/diagnose/

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.

diagnose official github The diagnose skill audits an AI workflow across five dimensions and returns scores with prioritized fixes. Use it before launch or after major workflow changes. CX Codex +1 209installs diagnose getagentseal diagnose — a router skill that helps a founder work out what is actually broken and pick one framework instead of guessing. CX Codex +1 811installs diagnose LegendApp diagnose — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that runs a structured bug investigation on explicit request. CX Codex +1 429installs diagnose pedrohcgs diagnose walks a failing run from a stable reproduction to a minimal example, ranked hypotheses and a fix. Built for research code. CX Codex +1 ★ 1,729repo stars azure-resource-health-diagnose official github The azure-resource-health-diagnose skill checks an Azure resource, uses its logs and telemetry to investigate issues, and drafts a remediation plan. Use it when you need to diagnose a specific resource. CX Codex +1 8,700installs diagnose-seo calm-north diagnose-seo runs structured technical SEO audits to detect crawl blocks, indexation errors, robots.txt mistakes, canonical issues, and JavaScript rendering failures. CX Codex +1 2,200installs diagnose-fix-loop LegendApp diagnose-fix-loop — a skill that keeps the agent looping: diagnose, make one scoped fix, verify with the same signal, diagnose again. It targets causes, not symptoms. CX Codex +1 426installs alibabacloud-elasticsearch-instance-diagnose aliyun alibabacloud-elasticsearch-instance-diagnose — a skill for analyzing Elasticsearch cluster health on Alibaba Cloud. Collects data from OpenAPI and REST API, identifies root causes of failures, and suggests remediation steps. CX Codex +1 127installs opik-diagnose comet-ml The opik-diagnose Claude Code skill ranks Opik traces by diagnostic signal. Run it to find production errors, slow calls, and failing tool use. CX Codex +1 111installs aws-resource-health-diagnose official github aws-resource-health-diagnose assesses AWS resource health, analyzes CloudWatch metrics and logs, and builds an actionable remediation plan for outages or performance drops. CX Codex +1 40installs

From the same set58

The whole set →
find-weakness find-weakness — a skill for Claude Code and Codex isolates the single strongest objection and the riskiest unstated assumption in any architectural choice or claim. CX Codex +1 ★ 26repo stars Envelope The Envelope Claude Code skill sorts requests into three actions: proceed, ask one question, or propose a plan first. It activates when an agent must decide whether to act or pause for clarification. CX Codex +1 ★ 26repo stars dream The dream Claude Code skill synthesizes session evidence into lessons and proposed changes. Run it to review recent sessions, consolidate notes, or spot recurring patterns. CX Codex +1 ★ 26repo stars digest The digest Claude Code skill reviews staged entries in MEMORY_CANDIDATES.md. It presents choices for each one: promote it, skip it, or replace an existing entry. CX Codex +1 ★ 26repo stars deep-recon The deep-recon Claude Code skill coordinates several agents to investigate a topic and create a structured recon document. It can draw on notes and web sources, with interactive or autonomous rounds. CX Codex +1 ★ 26repo stars decide This Claude Code skill weighs a decision against selected criteria and returns a structured recommendation. Run /decide to compare options or ask for help choosing a course of action. CX Codex +1 ★ 26repo stars critique-plan The critique-plan Claude Code skill challenges strategic plans, architectural decisions, and proposals before approval. It surfaces counterarguments, hidden assumptions, and alternatives. CX Codex +1 ★ 26repo stars context-hygiene This Claude Code skill archives old session log entries and trims active priorities. Run /context-hygiene to clean the context files. CX Codex +1 ★ 26repo stars

Project sponsors

Companies that keep this analytics open