AI agent skill · by @Houseofmvps

Learn

Manage project learnings across sessions. Save, search, recall, digest, prune, and export learnings that compound over time. Use when user wants to record, recall, or share project knowledge.

Archived 2026-10-23 · Source updated 2026-07-08 · License: MIT. Check the original repository for the latest version.

SKILL.md instructions

# Project Learnings Manager

Learnings are structured knowledge that compounds across sessions. They capture what worked, what didn't, decisions made, and patterns discovered — things that can't be derived from code alone.

**Announce at start:** "I'm using the learn skill to manage project learnings."

## Commands

### Save a learning

When the user discovers something worth remembering — a debugging insight, an architecture decision, a deployment gotcha, a tool preference:

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs save --title "Title here" --body "Detailed learning content" --tags "tag1,tag2"
```

**What to save:**
- Debugging insights ("Redis connection pool exhausts at 50 concurrent requests")
- Architecture decisions and their rationale ("Chose BullMQ over pg-boss because...")
- Deployment gotchas ("Railway needs `NODE_ENV=production` explicitly set")
- Performance findings ("Drizzle `select()` is 3x faster than `query()` for simple lookups")
- Integration quirks ("Polar.sh webhooks retry 3x with exponential backoff")

**What NOT to save:**
- Code patterns (read the code instead)
- Git history (use `git log`)
- Temporary debugging state (that's for the current session)

### Search learnings

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs search --query "keyword"
```

Search by title, body content, or tags. Returns all matches, unranked.

### Recall the most relevant learnings (ranked)

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs recall --query "keyword" [--limit N]
```

Prefer `recall` over `search` when you want the *most relevant* prior knowledge, not every match. It ranks by relevance (title > tag > body) with recency breaking ties, returns the top N (default 5) with one-line summaries and a score. Use this BEFORE starting work on a topic — it surfaces the learnings most likely to prevent a repeated mistake without dumping the whole history into context.

### Digest the whole knowledge base (compression)

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs digest
```

Produces a compact, grouped-by-topic snapshot — one line per learning, primary tag only — so a long history stays readable in a few tokens. Inject this at session start (or after a compaction) to carry forward what the project has learned without re-reading every learning file. This is the long-session memory primitive: `digest` to load context cheaply, `recall` to drill into a topic.

### List all learnings

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs list [--limit N]
```

### Prune old learnings

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs prune --older-than 90
```

Removes learnings older than N days. Default: 90 days. Run periodically to keep the knowledge base fresh.

### Export learnings

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs export --format markdown
node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs export --format json
```

Export for sharing with team members or backing up before a major refactor.

## Workflow Integration

**At session start:** Run `digest` to load a compact snapshot of what the project has learned, then `recall --query "<topic>"` when the user names a specific area — load cheap context first, drill in on demand.

**After debugging:** Save the root cause and fix as a learning — it will save hours next time.

**After deployment issues:** Save the gotcha — deployment problems recur.

**Before major changes:** Search for past learnings about the affected area.

**During retrospectives:** Use with `/retro` to cross-reference velocity data with learnings.

## Storage

Learnings are stored in `.ultraship/learnings/` in the project directory as JSON files. Each learning has:
- `id` — unique identifier
- `title` — short, searchable title
- `body` — detailed content
- `tags` — categorization for filtering
- `created_at` / `updated_at` — timestamps

Add `.ultraship/` to `.gitignore` if you don't want learnings in version control, or commit them to share with your team.