Skip to content
Skills Library
AI & agents · Writing

learn

/learn

Save a hard-won lesson or surprising fix so future sessions benefit. Boundary: learn records facts/gotchas; distill produces reusable multi-step procedures from conversation history. Use when: "save this to knowledge", "record this", "remember for next time", "/learn", "記下來", "存到 knowledge", "記住這個", user shares a gotcha or non-obvious fix, solution took 2+ attempts, environment-specific workaround discovered. Also handles: "knowledge health audit", "check MEMORY.md size", stale knowledge cleanup. Not for: active debugging, writing tests, project status updates, or extracting recurring procedur

Repository
autopilot ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
1
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Save a hard-won lesson or surprising fix so future sessions benefit. Boundary: learn records facts/gotchas; distill produces reusable multi-step procedures from conversation history. Use when: "save this to knowledge", "record this", "remember for next time", "/learn", "記下來", "存到 knowledge", "記住這個", user shares a gotcha or non-obvious fix, solution took 2+ attempts, environment-specific workaround discovered. Also handles: "knowledge health audit", "check MEMORY.md size", stale knowledge cleanup. Not for: active debugging, writing tests, project status updates, or extracting recurring procedur

Triggers from the description

save this to knowledgerecord thisremember for next time記下來存到 knowledge記住這個knowledge health auditcheck MEMORY.md size
Original author description

Save a hard-won lesson or surprising fix so future sessions benefit. Boundary: learn records facts/gotchas; distill produces reusable multi-step procedures from conversation history. Use when: "save this to knowledge", "record this", "remember for next time", "/learn", "記下來", "存到 knowledge", "記住這個", user shares a gotcha or non-obvious fix, solution took 2+ attempts, environment-specific workaround discovered. Also handles: "knowledge health audit", "check MEMORY.md size", stale knowledge cleanup. Not for: active debugging, writing tests, project status updates, or extracting recurring procedur

How it works

  1. When to Record
  2. Flow
  3. Categories
  4. Invocation
  5. Session Learning Summary (L-size)
  6. Knowledge Health Audit
Original SKILL.md headings · 176 lines, 801 words
SKILL.md preview
---
name: learn
description: >
  Save a hard-won lesson or surprising fix so future sessions benefit. Boundary: learn records
  facts/gotchas; distill produces reusable multi-step procedures from conversation history. Use
  when: "save this to knowledge", "record this", "remember for next time", "/learn", "記下來",
  "存到 knowledge", "記住這個", user shares a gotcha or non-obvious fix, solution took 2+ attempts,
  environment-specific workaround discovered. Also handles: "knowledge health audit",
  "check MEMORY.md size", stale knowledge cleanup. Not for: active debugging, writing tests,
  project status updates, or extracting recurring procedures from history (→ distill).
---

# learn

Record reusable knowledge so future sessions avoid the same mistakes.

## When to Record

| Trigger | Category |
|---------|----------|
| Bash command failed on path/config, then fixed | `env` |
| Compile error took 2+ retries to fix | `build` |
| Searched 3+ times to find a file/class | `env` |
| API usage was wrong, then corrected | `api` |
| Architecture decision required iteration | `arch` |

## Flow

1. **Dedup check** — search existing knowledge before writing:
   ```bash
   grep -ri "<keyword>" .claude/knowledge/*.md
   ```
   - Already recorded and complete: skip
   - Recorded but incomplete: update existing entry (Edit)
   - Not found: add new entry

2. **Read** the target knowledge file (by category):
   - `build-errors.md` | `debug-patterns.md` | `architecture.md` | `environment.md`

3. **Append** entry using this template:
   ```markdown
   ## [Title]
   **Date**: YYYY-MM-DD | **Context**: what you were doing
   **Problem**: what went wrong
   **Solution**: what fixed it
   ```
   Add `**Failed attempts**:` and `**Related**:` lines only when they add value.

4. **Update INDEX.md** "recent learning" table

5. **Rotate** — keep recent list at 10 entries max:
   ```bash
   # If your project has a rotate script:
   node .claude/scripts/learn-rotate.js
   # Otherwise: manually trim the oldest entries
   ```

## Categories

| Category | File | Content |
|----------|------|---------|
| `build` | `build-errors.md` | Compile/link/CMake errors |
| `debug` | `debug-patterns.md` | Debugging techniques, crash patterns |
| `arch` | `architecture.md` | Design decisions, pitfalls |
| `env` | `environment.md` | Paths, Docker, config |
| `api` | (in relevant file) | API misuse patterns |

## Invocation

```
/learn [category] [brief description]
```

Examples:
```
/learn build Missing dependency — install with apt/brew/pip
/learn env Script path wrong — use relative path from project root
```

---

## Session Learning Summary (L-size)

At the end of L-size tasks, produce a structured summary before the dev-flow session-end phase:

```markdown
### Errors Encountered
- [error] <problem> — Root cause: <cause> — Fix: <fix> — Recorded? Y/N

### Key Decisions
- [decision] <what was decided> — Reason: <why>

### Surprises
- <anything that was different from expected>

### Action Items for Future Sessions
- [ ] Record <item> to knowledge/<category>.md (if not yet recorded)
- [ ] Update skill <name> (if pattern repeated 3+ times)
- [ ] Refresh MEMORY.md (if applicable)
```

For S-size tasks: skip the full summary. Instead ask: "Did I retry any operation 2+ times?" If yes, record via standard flow above.

## Knowledge Health Audit

Run a structured health audit across all memory/knowledge files. Produce a status report with actionable remediation.

### 1. MEMORY.md Line Count

```bash
# Find the project memory file
find ~/.claude/projects/ -name "MEMORY.md" -path "*/memory/*" 2>/dev/null | head -1 | xargs wc -l
```

| Status | Lines | Why it matters |
|--------|-------|----------------|
| OK | <=170 | Safe margin |
| WARNING | 171-199 | Nearing truncation — Claude stops reading at line 200 |
| CRITICAL | >=200 | **Content after line 200 is silently lost** |

**Remediation**: Move detail sections to `memory/` sub-files, keep MEMORY.md as an index with links.

### 2. Knowledge File Sizes

```bash
wc -l .claude/knowledge/*.md 2>/dev/null
```

| Status | Lines | Why it matters |
|--------|-------|----------------|
| OK | <=300 | Reasonable read cost when invoked |
| WARNING | 301-500 | Read consumes ~2-4K tokens — diminishing ROI per entry |
| CRITICAL | >500 | Too expensive to read in full — entries get skipped |

**Remediation**: Archive old entries to `knowledge/archive/`, or split into sub-topic files.

### 3. Verification Staleness

Read first line of each knowledge file for `<!-- last-verified: YYYY-MM-DD -->`.

| Status | Age | Why it matters |
|--------|-----|----------------|
| OK | <=30 days | Trusted |
| STALE | 31-60 days | May contain outdated patterns |
| CRITICAL | >60 days or missing | High risk of wrong advice |

**Remediation**: Read the file, confirm each entry still applies, update the `last-verified` date.

### 4. INDEX.md Recent Learning Count

Count rows in the "recent learning" table (excluding header/separator).

| Status | Count |
|--------|-------|
| OK | <=10 |
| OVERFLOW | >10 — rotation needed |

**Remediation**: Trim oldest entries or run rotation script if your project has one.

### 5. Orphan Files

List `.md` files in `.claude/knowledge/` not referenced in INDEX.md.

**Remediation**: Add to INDEX.md, or delete if obsolete.

### Health Report Output Format

```
Memory Health Report (YYYY-MM-DD)

| Status | Item                  | Value     | Threshold |
|--------|-----------------------|-----------|-----------|
| ...    | MEMORY.md             | N lines   | <=200     |
| ...    | (each knowledge file) | N lines   | <=300     |

Stale Verification:
| File | Last Verified | Days Ago | Status |

INDEX.md Recent Learning: N / 10 — STATUS

Orphan Files: (none) or list

Recommended Actions:
1. [CRITICAL] ...
2. [WARNING] ...
```

Versions

RepositoryScoreLicence
This page · cookys/autopilot100MIT
lucamartins/ouroboros100MIT
boykush/scraps100MIT
nicsuzor/academicops100MIT
cookys/autopilot100MIT
joelhooks/PAROL6100MIT
tw93/Waza100MIT
fainir/agent-harness100MIT
amit429/understanding-map100MIT

Database snapshot: 13.11.2026 · package version b8997bccf983 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90shared-memory
    Use this skill whenever working on any task where the team may have relevant prior knowledge — coding, writing, research, analysis, customer work, process questions, compliance, onboarding, or any knowledge-intensive activity. Also use when the user corrects you, when you…
  • 80cmk:learn
    Use when the user asks to "remember this", "save this learning", "capture the key findings", "what do we know about X", "save that gotcha", or needs to extract and record non-obvious learnings, gotchas, and valuable knowledge from conversations, research sessions, debugging,…
  • 100distill
    Distill your recurring procedures and corrections from local conversation history into personal custom skills, routed into YOUR own skill dirs — never into autopilot. Boundary: learn records facts/gotchas; distill produces reusable procedures. Use when: "/distill", "what do I…
  • 95distill
    Distill your recurring procedures and corrections from local conversation history into personal custom skills, routed into YOUR own skill dirs — never into autopilot. Boundary: learn records facts/gotchas; distill produces reusable procedures. Use when: "/distill", "what do I…
  • 90adev:learn
    Capture a lesson learned as a heuristic in the project's memory store. Use when the user says 'remember this', 'save this lesson', 'learn that...', 'file a heuristic', 'we learned that...', or shares a rule/pattern that should persist across sessions. In Codex, invoke with $adev:learn
  • 100beacon-memory-distill
    Turn recorded agent sessions (Beacon traces from Claude Code, Cursor, Codex, OpenCode, and other harnesses) into reviewed, reusable project memory. Scores selected traces, reads the source trace behind each high-signal candidate, drafts a grounded lesson, and approves it only…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.