Skip to main content
skill CX Codex

learn · sethgammon — Claude Code skill: what it does, how to install

learn turns completed campaigns or evolve cycles into structured project wiki entries. Use it to carry decisions and recurring patterns into future sessions.

MIT ★ 937 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What learn does

The skill extracts successful approaches, failed attempts, and key decisions from a campaign, then adds the findings to topic-based wiki pages. It can also draft a quality-rule candidate when an issue was severe or appeared more than once. With no argument, it looks for the most recently completed campaign under .planning/campaigns/.

Findings first go into .planning/wiki/_staging/ and can then be compiled into the wiki. When a pattern already has a page section, learn adds evidence and records conflicting findings instead of silently replacing the existing explanation. That matters when later work needs to build on earlier campaign results.

A campaign run needs a completed campaign file; postmortems and audit telemetry are optional sources. You can select a campaign by slug or file path, or use an evolve pattern library with --from-evolve. A plain run has nothing to process until a campaign is complete.

What it helps with

  • carry successful campaign methods into the project wiki
  • record failed approaches and their failure modes
  • compare new findings with documented patterns
  • compile findings from an evolve pattern library

Example prompts for the agent

  • Compile findings from the latest completed campaign with /learn.
  • Add the findings from campaign checkout-redesign to the wiki using /learn checkout-redesign.
  • Compile evolve patterns for checkout with /learn --from-evolve checkout.

How to install learn

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill learn -a claude-code

3Manually: put the files in place

~/.claude/skills/learn/SKILL.md

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

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

Questions about learn

How do I install learn in Claude Code?

Run /plugin marketplace add SethGammon/Citadel, then run /plugin install citadel@citadel-local.

What does the learn skill do?

It extracts patterns, decisions, and failed approaches from completed campaigns or evolve cycles, then incorporates them into the project's topic-based wiki.

What can I use as input for learn?

Choose the latest completed campaign, pass a campaign slug or file path, or provide an evolve pattern library with --from-evolve. A postmortem and audit telemetry can supplement campaign findings.

Source text

SKILL.md · MIT
---
name: learn
license: MIT
description: >-
  Knowledge compiler. Extracts patterns, decisions, and anti-patterns from
  completed campaigns and evolve cycles, then compiles them into structured wiki
  pages that integrate with existing knowledge rather than appending isolated
  files. Implements flush→compile→lint pipeline. Auto-triggered by /postmortem
  and /evolve Phase 6.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - learn
  - extract patterns
  - learn from that
  - save what worked
  - patterns from campaign
last-updated: 2026-05-07
---

# /learn — Knowledge Compiler

## Orientation

**Use when:** You have a completed campaign or evolve cycle and want to compile
its findings into the project's growing knowledge wiki — so future sessions
start smarter, not from scratch.

**Don't use when:** You want a structured incident analysis first (use `/postmortem`
— run it before `/learn`); you haven't finished any campaigns (nothing to compile);
you want a context transfer only (use `/session-handoff`).

**Key difference from appending:** `/learn` doesn't create isolated per-campaign
files. It integrates new findings into existing wiki pages — updating evidence
lists, raising confidence where a pattern is confirmed again, and flagging
contradictions. A wiki is a compiler; a log is an interpreter.

## Invocation Forms

```
/learn                              — most recently completed campaign
/learn {slug}                       — specific campaign by slug
/learn {file-path}                  — specific campaign file path
/learn --from-evolve {target}       — compile from /evolve pattern library
/learn --from-evolve {target} --cycle {n}  — specific evolve cycle only
/learn --lint                       — lint-only pass (no new extraction)
/learn --compile                    — re-compile staging area into wiki (no new extraction)
/learn --memory                     — compile semantic memory blocks from planning artifacts
/learn --doc-sync                   — process doc-sync queue into .planning/doc-sync/latest.md
```

## Inputs

1. A campaign slug, file path, evolve target, or "most recent" resolution
2. Corresponding postmortem in `.planning/postmortems/` (optional)
3. `.planning/telemetry/audit.jsonl` filtered to this campaign (optional)
4. For `--from-evolve`: `.planning/evolve/{target}/pattern-library.md`

## Protocol

### Step 1: RESOLVE TARGET

**If `/learn` (no argument):**
- Glob `.planning/campaigns/completed/*.md` or `.planning/campaigns/*.md`
  where `Status: completed`
- Sort by modification time descending, take most recent
- If none found: "No completed campaigns found. Run /learn after a campaign completes." Stop.

**If `/learn {slug}`:**
- Search `.planning/campaigns/` for a file whose name contains `{slug}`
- Check `.planning/campaigns/completed/` if not found in active
- If still not found: "No campaign found matching '{slug}'."

**If `/learn --from-evolve {target}`:**
- Read `.planning/evolve/{target}/pattern-library.md` — this is the source
- If `--cycle {n}`: filter to sections beginning with `## Cycle {n}` only
- If file not found: "No evolve pattern library for '{target}'." Stop.

**If `/learn --doc-sync`:** Run:
```
node hooks_src/doc-sync.js
```
Then review `.planning/doc-sync/latest.md`. Stop after reporting the queue count,
files surfaced, skipped deleted files, and report path. Do not run campaign
extraction unless the user separately asks for it.

**If `/learn --lint`, `/learn --compile`, or `/learn --memory`:** Skip to Step 4, 5, or 5.5 respectively.

### Step 2: GATHER SOURCES

For campaign-based runs only (skip for `--from-evolve`):

**Campaign file (required):**
- Full content — direction, phases, Decision Log, circuit breaker activations

**Postmortem (optional):**
- Search `.planning/postmortems/` for files matching `*{slug}*`
- If not found: note "Postmortem not found — proceeding without it" and continue

**Audit telemetry (optional):**
- Read last 200 lines of `.planning/telemetry/audit.jsonl`
- Filter entries that match the campaign slug or its active period
- If none: note "No audit telemetry found for this campaign"

### Step 3: FLUSH

Extract raw findings and write to staging.

**For campaign sources:**

Extract four categories:

**A. Successful Patterns** — approaches that demonstrably worked (phases completed without rework, postmortem positives, no reverts).
Per pattern: `name`, `mechanism` (what caused success), `evidence` (phase/commit/entry), `topic` (infer from subject matter), `applicability`.

**B. Anti-patterns** — what was tried and failed (rework phases, circuit breaker trips, quality gate blocks, reverts).
Per pattern: `name`, `what-was-tried`, `failure-mode`, `evidence`, `topic`, `avoidance`.

**C. Key Decisions** — from Decision Log or inferred from phase descriptions.
Per decision: `what`, `rationale`, `outcome` (completed or rework).

**D. Quality Rule Candidates** — only generate if: specific regex, applies to a specific file pattern, occurred more than once or was severe. Per candidate: regex, file pattern, trigger message, confidence (`high`/`medium`/`low` — skip `low`).

**For evolve sources:**

Parse the pattern library's sections. For each pattern record:
- `name`: section heading
- `mechanism`: "**Mechanism:**" field
- `delta`: "**Delta:**" field
- `topic`: infer from "**Axis class:**" (e.g., `orientation_precision` → `skill-orientation`)
- `applies-to`: "**Applies to:**" field
- `confidence`: "**Confidence:**" field
- `evidence`: source file + cycle number

**Staging write:**

Create `.planning/wiki/_staging/` if it does not exist.
Write staged findings to `.planning/wiki/_staging/{source-slug}-{timestamp}.jsonl` —
one JSON record per finding (newline-delimited).

If zero findings are extractable: write staging file with a single `{"type":"empty","source":"{slug}"}` record and note "Campaign may have been too brief."

### Step 4: COMPILE

Integrate staged findings into wiki pages.

Create `.planning/wiki/` if it does not exist.

For each staged finding:
1. Determine the wiki page: `.planning/wiki/{topic}.md` where `topic` is the finding's `topic` field (normalized to kebab-case).
2. Read the wiki page if it exists.
3. **If the page exists and contains a section for this pattern** (match on `## {name}`):
   - Append the new source to the `**Evidence:**` list
   - Update `**Last confirmed:**` to today
   - If new confidence >= existing confidence: raise it
   - If new evidence contradicts the existing mechanism: add a `**Conflict:**` field — do not silently overwrite
4. **If the page exists but has no section for this pattern:**
   - Append a new section with the full finding
5. **If the page does not exist:**
   - Create it with the frontmatter template (see below) and the finding as the first section

**Wiki page format:**
```markdown
---
topic: {slug}
last-compiled: {ISO date}
sources: {N}
---

# {Topic Title}

## {Pattern Name}
**Mechanism:** {what causes success/failure}
**Evidence:** {source-1 (date)}, {source-2 (date)}, ...
**Confidence:** high/medium/low
**Last confirmed:** {ISO date}
**Applies to:** {scope}
```

After compiling all findings: update `.planning/wiki/index.md` —
one line per wiki page: `- [{topic}]({topic}.md) — {one-line description}`.
Create `index.md` if it does not exist.

### Step 5: LINT

Scan all `.planning/wiki/*.md` pages (skip `index.md`).

**Contradiction check:** For each page, if two sections contain opposing directives
("always X" vs "never X", "prefer X" vs "avoid X"), flag as:
`CONFLICT: [{page}] {section-A} contradicts {section-B} — requires human resolution`

**Staleness check:** Sections with `**Last confirmed:**` older than 60 days are flagged as:
`STALE: [{page}] {section} — last confirmed {date}, consider re-testing`

**Coverage check:** Warn if a wiki page has fewer than 2 sections — single-entry pages are fragile.

Lint results are reported in the summary. Lint does not modify wiki pages.

### Step 5.5: COMPILE SEMANTIC MEMORY BLOCKS

Run a safe deterministic memory compile pass:

```
node scripts/memory-compile.js compile
```

This writes compact semantic blocks to `.planning/memory/blocks/` and updates
`.planning/memory/index.json`. Blocks must include `id`, `type`, `scope`,
`owner`, `confidence`, `last_verified`, `sources`, and `body`.
Compile only source-supported categories; absent categories and zero blocks are valid.
Default context listing excludes stale/unverified records, including digestless legacy notes.

For lint-only memory checks, run:

```
node scripts/memory-compile.js lint
```

For agent context loading, use scoped listing instead of rereading full
histories:

```
node scripts/memory-compile.js list --scope verification
node scripts/memory-compile.js list --query "Fleet readiness"
```

Memory block lint must pass before calling the compile successful. Missing
source paths, changed or unverified source bytes, stale blocks, and contradictions
are reported as actionable failures.

### Step 6: APPEND QUALITY RULES

`.claude/harness.json` is Citadel's shared configuration path for every runtime, including Codex. Create that path when it is missing; do not substitute a runtime-specific config file.

For each high/medium-confidence rule candidate in the staged findings:
1. Read `.claude/harness.json` (create with `{}` if missing)
2. Initialize `qualityRules.custom` to `[]` if absent
3. Skip if a rule with the same `pattern` already exists
4. Append: `{ "name": "auto-{slug}-{N}", "pattern": "{regex}", "filePattern": "{glob}", "message": "Learned from {slug}: {message}" }`
5. Write updated harness.json

Skip low-confidence rules.

### Step 7: OUTPUT SUMMARY

For the optional promotion in the summary, Codex uses `AGENTS.md`. Claude Code uses
`CLAUDE.md` when the project has one; where its `AGENTS.md` capability is available,
the default uses `AGENTS.md` if no project `CLAUDE.md` exists. The operator can
configure Claude Code to load both under **Project instructions**. Check the active
setting or startup notice before choosing a file, and do not duplicate a rule into
an instruction file the runtime is not loading. Preserve user-authored guidance.

```
=== /learn: {Source} ===
Mode: {campaign | evolve-{target} | lint-only | compile-only}
Sources: {campaign path | evolve path} | postmortem {path or "not found"} | {N} audit entries
Staged: {N} findings → .planning/wiki/_staging/{file}
Compiled: {N} patterns integrated | {M} new wiki sections | {K} existing sections updated
Wiki pages: .planning/wiki/{topic-1}.md, ...
Lint: {conflicts found | clean} | {stale entries} | {coverage warnings}
Memory blocks: {N} compiled | lint {PASS|FAIL} | .planning/memory/index.json
Rules added to harness.json: {M} ({K} skipped — already exist)
Next: review .planning/wiki/index.md — promote stable patterns to the project's active instruction file(s).
```

## Fringe Cases

**No completed campaigns:** Output message and stop.

**`.planning/` does not exist:** Bare `/learn` follows Step 1's "No completed campaigns found" response and stops without creating files. Other invocation forms output "Run /do setup first to initialize the harness state directory." Stop.

**No Decision Log:** Extract decisions from phase descriptions; note "inferred from phase descriptions."

**harness.json missing:** Create with only the qualityRules section; do not invent other fields.

**Duplicate quality rule:** Skip silently; count in "skipped — already exist."

**Postmortem missing:** Proceed without it; note in summary.

**Large telemetry file:** Read last 200 lines only.

**Zero extractable findings:** Write staging file noting source was empty. Do not skip wiki/index update.

**Wiki page conflict detected at compile time:** Add a `**Conflict:**` field to the section. Never silently overwrite the existing mechanism.

**Memory compile has missing sources:** Report the missing source paths and keep
the existing memory blocks untouched until the source issue is resolved.

**Doc-sync queue empty:** Output "No doc-sync work is queued." Stop.

**Doc-sync queue has only surfaced entries:** Output "All doc-sync items are already surfaced." Stop.

**evolve pattern-library.md missing:** "No evolve pattern library for '{target}'. Run /evolve {target} first to generate patterns." Stop.

## Contextual Gates

**Disclosure:** "Compiling findings into .planning/wiki/. Modifies wiki pages in-place; creates staging files."
**Reversibility:** green — all writes are to `.planning/wiki/` and `.planning/wiki/_staging/`; `git restore .planning/wiki/` or delete the directory to undo. Quality rule additions to harness.json can be manually removed.
**Trust gates:**
- Any: run on any completed campaign or evolve target

## Quality Gates

- Never invent patterns not supported by evidence in the source files
- Never write a quality rule with confidence < medium
- Never duplicate an existing quality rule (check before appending)
- Wiki index must be updated on every compile run
- Lint must run after every compile (not skipped)
- Memory block lint must pass after `--memory` or the Step 5.5 compile pass
- `/learn --doc-sync` must leave no `pending` or `needs-review` entries for
  processed queue items unless run with `--dry-run`
- Conflicts must be flagged, never silently resolved
- Summary output must include counts for all phases

## Exit Protocol

/learn does not produce a full HANDOFF block (it is a utility, not a campaign).
It outputs the summary block in Step 7 and waits for the next command.

© SethGammon · MIT · SethGammon/Citadel

Similar skills

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

learn by other authors comes first.

learn rohitg00 learn is a Claude Code skill that teaches the AI Engineering from Scratch course in the terminal, section by section, quizzes at the end, and records progress. CX Codex +1 5,200installs learn tw93 learn — a six-phase research workflow that turns source material into notes, an outline, or a publish-ready draft. Use it for unfamiliar domains and multi-source work. CX Codex +1 13,600installs learn giuseppe-trisciuoglio learn analyzes a codebase to discover architectural patterns and conventions, then creates rule files in .claude/rules/. Useful when joining a new codebase. CX Codex +1 3,500installs learn Claude Code Academic Workflow learn extracts non-obvious fixes and workflows from your session into persistent skills. Useful when an undocumented workaround needs to be reused across future runs. CX Codex +1 ★ 1,729repo stars Learn wrg32786 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 llmwiki atomicstrata llmwiki is an MCP server for Claude Code that turns documents into a linked wiki with citations for agent search and reading. It organizes notes, PDFs, and other sources into reusable, auditable knowledge. CX Codex +1 ★ 2,275repo stars learn-taste emilkowalski learn-taste — a Claude Code skill turns design feedback into rules and records the reasoning behind them. It reviews session corrections and proposes which ones should carry into later work. CX Codex +1 13,700installs learn-codebase thedotmack learn-codebase — a skill for Claude Code, Codex, Cursor and other AI coding platforms that reads every source file in the project from start to finish. Runs when the user asks to learn, read or prime the codebase. CX Codex +1 5,800installs learn-agent-skills rohitg00 Interactive tutor for the Agent Skills Engineering track. Teaches one lesson per call, guides hands-on labs, and logs evidence to AGENT-SKILLS-LEARNING.md. CX Codex +1 3,700installs learn-docker-k8s-game reason-machines learn-docker-k8s-game — a skill for Claude Code, Codex, Cursor and other AI editors that turns the chat into a story-driven Docker and Kubernetes training game, running real terminal commands at each step. CX Codex +1 801installs Mailchimp Automation Claude Office Skills Mailchimp Automation — a skill that automates Mailchimp email marketing: builds campaigns, segments subscribers, sets up email sequences and reads engagement reports. CX Codex +1 4,800installs

From the same set55

The whole set →
watch watch monitors working directory changes and source marker comments to trigger skills or log batch tasks automatically. CX Codex +1 ★ 937repo stars telemetry Displays session cost, spending today and all-time totals, hook activity, trust level, and a directory of telemetry commands. CX Codex +1 ★ 937repo stars experiment experiment runs scalar-metric optimization loops in isolated worktrees, checking each candidate against a locked baseline before it's kept. CX Codex +1 ★ 937repo stars research research investigates technical questions, cross-references documentation, and saves structured Markdown briefs with confidence ratings. CX Codex +1 ★ 937repo stars dashboard dashboard is a Claude Code skill that shows harness state, including campaigns, agent sessions, telemetry, and queues. Run it with /dashboard, /do status, or a request to show activity. CX Codex +1 ★ 937repo stars evolve evolve — a skill for Claude Code and Codex that drives iterative code advancement by forming hypotheses about why scores stall, validating them with scout agents, and coordinating targeted fixes across cycles. CX Codex +1 ★ 937repo stars improve The skill scores a target against a rubric, picks one area to work on, then checks the result. Use it for repeatable improvement cycles rather than a one-off bug fix. CX Codex +1 ★ 937repo stars daemon daemon keeps a Citadel campaign going by chaining Claude Code sessions one after another until the budget or phase runs out. CX Codex +1 ★ 937repo stars

Project sponsors

Companies that keep this analytics open