learn

learn501 wordsMITRepo-owned

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.

Quick Start

Install:

npx skills add github:wyattowalsh/agents --skill learn -y -g --agent antigravity --agent claude-code --agent codex --agent crush --agent cursor --agent gemini-cli --agent github-copilot --agent grok --agent opencode

Use: /learn [correction or insight to capture]

Research context (evidence, not authority)

Problem: 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. Stack / assumptions: portable skill scripts under scripts/; on-demand references; eval fixtures Comparable alternative: A general-purpose agent instruction without a scoped skill contract

Works with Claude Code, Gemini CLI, OpenCode, and other agentskills.io-compatible agents.

Repo skill (hand-maintained)

Composed compose-custom-wave-5 from skills/learn/SKILL.md with full SKILL disclosure. Do not run wagents docs generate on this file (HAND-MAINTAINED sentinel).

What It Does

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

Modes

$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

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)

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. Step — Incremental > revolutionary — Smallest viable change, verify before next

2. Step — Poka-yoke — Prefer hooks/tooling over prose instructions (error-proof by design)

3. Step — Standards work — Follow existing patterns, document what works

4. Step — JIT — Build only what is needed, optimize when measured

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:

python scripts/check.py

Completion criteria:

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

Public Metadata

Field	Value
Source Type	repo-owned
Display Source	github:wyattowalsh/agents
Source Kind	repo
Installability	portable command
Review State	reviewed
Target Agents	antigravity, claude-code, codex, crush, cursor, gemini-cli, github-copilot, grok, opencode

General

Field	Value
Name	learn
License	MIT
Version	1.0.0
Author	wyattowalsh

Claude Code

Field	Value
Argument Hint	[correction or insight to capture]

Related Skills

python-conventions Enforce Python tooling conventions for uv, ty, Ruff, pytest, and pyproject.toml. Use when working on .py files or Python project config.

javascript-conventions Configure and validate JS/TS tooling conventions. Enforce pnpm, TypeScript, ESLint, and Prettier defaults. Use when working on JS/TS files or package.json.

agent-conventions Agent definition conventions. Validate frontmatter, update indexes. Use when creating or modifying agents. NOT for skills, MCP servers, or CLAUDE.md.

View Full SKILL.md

SKILL.md

---
name: learn
description: >-
  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.
argument-hint: "[correction or insight to capture]"
user-invocable: true
disable-model-invocation: false
license: MIT
metadata:
  author: wyattowalsh
  version: "1.0.0"
---

# 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.

Download from GitHub

Resources

Skill Catalog Browse custom and external skills.

CLI Reference Install and manage skills.

agentskills.io The open ecosystem for cross-agent skills.

---

View source on GitHub