# Learn

> Capture corrections and patterns as reusable knowledge. Routes to the right instruction file. Use when patterns repeat 3+ times or to save insights. NOT for one-time fixes or code review.

- Skill: `wyattowalsh/learn` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add wyattowalsh/learn`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wyattowalsh/learn/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: wyattowalsh (https://skillmd.com/u/wyattowalsh)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wyattowalsh/learn

---


# Learn — Capture and Route Project Knowledge

Record corrections, insights, and patterns. Route them to the correct instruction file. Apply kaizen principles to keep instructions lean and effective.

## Dispatch

| `$ARGUMENTS` | Action |
|---|---|
| `"<correction text>"` | Route correction to appropriate instruction file |
| `review` | Show pending learnings and their frequency |
| `promote` | Promote high-frequency learnings (3+ occurrences) to instruction files |
| `audit` | Check for stale, contradictory, or duplicate learnings |
| Empty | Display usage summary |

## References

| File | Purpose |
|------|---------|
| `references/routing-rules.md` | Decision tree for where to route instruction changes |
| `references/kaizen-principles.md` | Error-proofing patterns, when to use hooks vs prose vs rules |

## Routing Protocol

Route proposed updates to the correct target:

| Scope | Target |
|-------|--------|
| Cross-project conventions | `instructions/global.md` |
| Language-specific tooling | Convention skill (`python-conventions`, etc.) |
| Orchestration/parallelism | `orchestrator` skill body |
| Project-specific standards | Project's `AGENTS.md` |
| File-scoped enforcement | `.claude/rules/<topic>.md` |
| Skill behavior | The skill's own `SKILL.md` |

### Routing Decision Steps

1. Determine the scope: does this apply to all projects or just one?
2. If cross-project, does it relate to a specific language or tool?
3. If language-specific, route to the corresponding convention skill
4. If general, route to `instructions/global.md`
5. If project-only, route to the project's `AGENTS.md`
6. If file-scoped enforcement only, create a `.claude/rules/` entry

## Kaizen Principles

1. **Incremental > revolutionary** — Smallest viable change, verify before next
2. **Poka-yoke** — Prefer hooks/tooling over prose instructions (error-proof by design)
3. **Standards work** — Follow existing patterns, document what works
4. **JIT** — Build only what is needed, optimize when measured

## Verification Checklist

1. Verify against actual practice — confirm the pattern reflects real usage
2. Check for contradictions with existing instructions
3. Assess token impact — keep always-loaded content minimal
4. Get user approval — never modify instruction files without consent
5. Test the change — run `python scripts/check.py` after any instruction file edit

## Critical Rules

1. Never modify instruction files without explicit user approval
2. Require 3+ corrections across 2+ sessions before promoting
3. Check for contradictions with existing instructions
4. Route to narrowest applicable scope (rule before skill, skill before global)
5. Keep always-loaded content under token budget
6. Run `python scripts/check.py` after every instruction file modification
7. Prefer hooks/rules over prose (poka-yoke principle)

## Canonical Terms

- `instruction file` — any file that provides agent instructions (global.md, AGENTS.md, SKILL.md)
- `routing` — the process of choosing the correct target file for a change
- `correction pattern` — a repeated fix that indicates a missing or wrong instruction
- `token budget` — the limit on always-loaded instruction content
- `scope` — cross-project, language-specific, orchestration, project-specific, or file-scoped

## Validation Contract

Run from this skill directory before declaring changes complete:

```bash
python scripts/check.py
```

Completion criteria:

1. `scripts/check.py` exits 0.
2. No portable-CLI violations remain under this skill directory.