# Learn

> Quick-capture a learning during a session without interrupting flow. Appends to the knowledge base immediately.

- Skill: `antonioshaman/learn` (Agent Skill)
- Install (CLI): `npx skillmds@latest add antonioshaman/learn`
- Raw SKILL.md: https://api.skillmd.com/api/skills/antonioshaman/learn/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: antonioshaman (https://skillmd.com/u/antonioshaman)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/antonioshaman/learn

---


Capture a learning right now, mid-session, without breaking flow.

## Process

### 1. Parse the Insight

From the user's input or the current context, determine:
- **Type**: Is this a pattern, gotcha, decision, anti-pattern, codebase-fact, or api-behavior?
- **Confidence**: Did we verify this (high), observe it (medium), or suspect it (low)?
- **Tags**: What files, features, or areas does this relate to?

### 2. Check for Duplicates

Read the target `.jsonl` file and check if a similar entry already exists:
- If yes → **re-confirm the existing entry** (do NOT append a duplicate):
  - bump `helpfulCount` by 1
  - bump `confidence` if previously `low`/`medium` and the new evidence is strong
  - set `updatedAt` to now
  - update `recommendation` only if it's clearly better
- If no → append a new entry

### 3. Write Entry

Append to the appropriate file in `.agents/knowledge/`. Field order matches `.agents/knowledge/README.md`:

```json
{
  "id": "<type-prefix>-<next-number>",
  "type": "<detected-type>",
  "fact": "<concise insight>",
  "recommendation": "<what to do about it>",
  "confidence": "<detected-confidence>",
  "provenance": [{"source": "<human|agent|test-failure>", "reference": "<context>", "date": "<today>"}],
  "tags": ["<relevant>", "<tags>"],
  "affectedFiles": ["<paths>"],
  "createdAt": "<now ISO>",
  "updatedAt": "<now ISO>",
  "usageCount": 0,
  "helpfulCount": 0,
  "outdatedReports": 0
}
```

`usageCount` is bumped by `/prime` when surfacing, `helpfulCount` by `/learn` on re-confirmation, `outdatedReports` by `/self-reflect` or the user when an entry is flagged stale.

### 4. Confirm

Output a one-liner:

```
📝 Learned: [fact] → saved to [category] (confidence: [level])
```

Then continue with whatever you were doing.

## Examples

User says: `/learn the recorder auto-rotates at 1M lines`
→ Saves as codebase-fact with tags `["recorder", "rotation"]`

User says: `/learn don't use window.location for routing, use hash routing`
→ Saves as anti-pattern with tags `["routing", "frontend"]`

Agent encounters unexpected behavior during work:
→ Auto-captures as gotcha with `source: "agent"`

## Auto-Learn Triggers

During normal work, automatically capture learnings when:
- A test fails for a non-obvious reason
- The user corrects your approach ("no, don't do it that way")
- You discover an undocumented API behavior
- A code review reveals a missed pattern
- You find something that contradicts an existing knowledge entry