Skip to main content
skill CX Codex

learn-from-failure — Claude Code skill for recurring errors

The learn-from-failure Claude Code skill classifies failures and checks whether their causes have appeared before. Repeated problems lead to a durable artifact meant to prevent another recurrence.

MIT ★ 26 updated 2026-11-16

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

What learn-from-failure does

The skill classifies a failure, searches $AIGENT_VAULT/memory/FAILURE_MODES.md for matching patterns, then adds an entry to the ledger. With 0–1 earlier occurrences, it logs and monitors the issue; at 2 or more, it requires an artifact. At 3 or more, it treats the earlier artifact as failed and calls for diagnosis and repair or replacement.

The failure category determines the artifact: routing problems change a skill description or add a hook, while verification problems add a runnable check to a doctrine note. Tool failures go into SKILL_GAPS.md; knowledge gaps become notes, and authority violations are surfaced to the operator. The skill needs $AIGENT_VAULT and its memory/FAILURE_MODES.md ledger.

Run /learn-from-failure with an optional failure description. If the command has no argument, the skill asks what went wrong.

What it helps with

  • classify the cause of a failure
  • find earlier instances of the same problem
  • decide when a recurring issue needs a lasting fix
  • record the cause, remedy, and affected system layer

Example prompts for the agent

  • Analyze this recurring failure: the agent picked the wrong tool.
  • /learn-from-failure The data verification error happened again.
  • /learn-from-failure Log the Gmail MCP authentication failure and check for earlier cases.

How to install learn-from-failure

1Skills CLI (Vercel)

npx skills add wrg32786/aigent-os --skill learn-from-failure -a claude-code

2Manually: put the files in place

~/.claude/skills/learn-from-failure/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/learn-from-failure/

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

Questions about learn-from-failure

How do I install learn-from-failure in Claude Code?

Run npx skills add wrg32786/aigent-os --skill learn-from-failure -a claude-code. The skill file is installed at ~/.claude/skills/learn-from-failure/SKILL.md.

What does learn-from-failure do?

It classifies a failure, checks the ledger for matching causes, and selects an artifact to capture the remedy. Repeated failures trigger a lasting fix; after the third occurrence, the earlier artifact is diagnosed and repaired or replaced.

What does learn-from-failure need to run?

It needs $AIGENT_VAULT with the memory/FAILURE_MODES.md ledger. The skill searches that file for recurring patterns and appends new failure records.

Source text

SKILL.md · MIT
---
name: learn-from-failure
description: "Convert failures into reusable artifacts and check repetition. Use when analyzing a failure mode or a recurring failure."
---

# /learn-from-failure — Convert failure to reusable artifact

When a failure occurs, classify it, check for repetition, and produce a durable artifact that prevents recurrence.

## Trigger

`/learn-from-failure` or `/learn-from-failure <failure description>`

Use on: "same issue", "happened again", "recurring", "third time", "keeps happening"

## Flow

### 1. Identify failure
- If argument provided: use it
- If no argument: ask "What failed?"

### 2. Classify failure mode

| Mode | Description | Example |
|------|-------------|---------|
| `routing` | Task sent to wrong agent/model/tool | Opus used for a read-only task |
| `verification` | Output accepted without checking data flow | Video "looked fine" but spec was wrong |
| `tool` | Tool unavailable, broken API, wrong usage | Gmail MCP auth expired |
| `knowledge` | Agent lacked domain knowledge | Didn't know SDK v6 changed type strings |
| `authority` | Agent acted outside delegation zone | the AIgent made a Level 3 decision |

### 3. Check for repetition
Read `$AIGENT_VAULT/memory/FAILURE_MODES.md`. Search for Pattern lines matching the current failure's root cause.

- **0-1 prior occurrences:** Phase 1 — log and monitor
- **2+ occurrences:** Phase 2 — mandatory artifact. A log entry is not enough.
- **3+ occurrences:** The prior artifact failed. Diagnose why and fix or replace it.

### 4. Log to FAILURE_MODES.md
Append a new entry following the existing format:

```markdown
## {YYYY-MM-DD} — {short symptom name}

**Symptom:** {what went wrong, user-visible}
**Verified cause:** {exact mechanism}
**Fix:** {what was done}
**Layer:** {which system layer}
**Pattern:** {one-line category — this is the load-bearing piece for repetition detection}
```

### 5. Determine artifact type

| Failure mode | Artifact | Target |
|---|---|---|
| `routing` | Skill description or hook | the skill's `SKILL.md` description, or `.claude/hooks/` |
| `verification` | Checklist item in doctrine | Relevant doctrine note |
| `tool` | SKILL_GAPS entry + skill spec | `memory/SKILL_GAPS.md` |
| `knowledge` | Vault note or memory candidate | `concepts/` or `memory/` |
| `authority` | Flag to the operator | `aigent_authority_matrix.md` |

### 6. Create artifact
- For routing: add 3+ trigger phrases to the skill's `description` ("Use when ...")
- For verification: append a concrete, runnable check to the relevant doctrine
- For tool: log to SKILL_GAPS.md, suggest /skill-hunt if external capability needed
- For knowledge: write a memory candidate or vault note
- For authority: surface to the operator with recommendation

### 7. Output
```
Failure logged: {classification}
Pattern: {pattern line}
Repeated: {yes/no, count}
Artifact: {type} at {path}
```

## Boundary

Per [[Self-Learning Doctrine]]: a failure logged without an artifact is a false resolution. The ledger grows, the failure recurs, the system learns nothing.

## Bounded procedure experiment (fixture only)

A Finding is an observation, not a verified cause or authority to edit a procedure.
The [fixture mechanics](../../evals/procedure-experiment/README.md) use a declarative grammar and a pinned historical corpus.
Freeze the candidate, evidence, corpus, size budgets and rollback before evaluating.
Require a passing verdict and a caller-supplied approval bound to the candidate and base.
Distinct identity strings are not authenticated review.
This proves mechanics on a fixture, not natural-language procedure compliance or live behavior.

## Related

- [[concepts/Self-Learning Doctrine]] — the doctrine this skill implements
- [[memory/FAILURE_MODES.md]] — the ledger
- [[concepts/Capability Expansion Doctrine]] — tool failures feed the expansion loop
- [[Self-Improving CLAUDE.md]] — the broader self-improvement cycle

© wrg32786 · MIT · wrg32786/aigent-os

Similar skills

SKILL.md skills catalog →

From the same set58

The whole set →
nightly-close-parity This skill for Claude Code runs a project’s nightly close-parity maintenance. It checks the local route first, then follows the protocol stored in the project. CX Codex +1 ★ 26repo stars meta-improve A Claude Code skill applies operator-approved Dream candidates through a gated change process. Run it with /meta-improve-vault before building the change. CX Codex +1 ★ 26repo stars memory-bridge The memory-bridge Claude Code skill connects explicit memory requests to Hindsight and Jev. Ask it to retain, recall, or reflect on a note to trigger the bridge. CX Codex +1 ★ 26repo stars Learn The Learn Claude Code skill turns research on a repo, talk, or tool into a structured note. It records an assessment and, for HOLD decisions, a condition for reviewing it again. CX Codex +1 ★ 26repo stars impeccable The impeccable Claude Code skill guides frontend design, helps establish a project’s visual direction, and can extract components and design tokens. It needs context about users, their tasks, and the brand’s tone. CX Codex +1 ★ 26repo stars humanize-docs humanize-docs is a Claude Code skill that transforms robotic documentation into natural prose. It rewrites technical docs and README files by removing repetitive checklists and rigid section structures. CX Codex +1 ★ 26repo stars Honesty Check The Honesty Check Claude Code skill builds an honesty ledger for completed work. It runs before an agent reports a task as done or prepares it for review. CX Codex +1 ★ 26repo stars first-win This Claude Code skill offers three starter tasks that end with a usable artifact. Run /first-win to turn a post into social content, shape an idea into a plan, or sort email into priorities. CX Codex +1 ★ 26repo stars

Project sponsors

Companies that keep this analytics open