# Learning Insights

> Internal-only skill — never called directly by users. Provides the Learning Intelligence Layer. Two modes: "build context" (called by /learn at session start) reads learning history and produces a learner context; "update insights" (called by /end-learn after session close) updates the persistent insights.md summary.

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

---


## Overview

Centralized intelligence layer that mines past session data to improve current
learning sessions. Not user-facing — invoked by `/learn` and `/end-learn` only.

## Mode 1: Build Context

Called by `/learn` at session start, before content delivery.

### What to Read

1. `~/.claude/learning/insights.md` — persistent summary (may not exist yet)
2. `~/.claude/learning/lessons/archive/` — scan all archived lessons for:
   - `## Still Fuzzy On` sections
   - `## Key Learnings` sections
   - `status` frontmatter (completed / postponed / abandoned)
   - `sessions` count vs milestone count (was the lesson harder than estimated?)
3. `~/.claude/learning/logs/` — scan recent session logs (last 30 days) for:
   - `## Struggled With` sections
   - `## Still Fuzzy On` sections
   - `## Key Learnings` sections

### What to Produce

Return a learner context to the calling skill (kept in conversation, not written to disk):

**fuzzy_topics:**
Themes that appear in "Still Fuzzy On" across archived lessons or recent logs.
Include the source lesson and how recently it was seen.
Example:
- "async error handling" — from LangChain lesson, 2 sessions ago
- "state persistence" — from LangGraph lesson, last week

**difficulty_adjustment:**
Per-gap difficulty level based on performance patterns:
- `beginner` — struggled with basics, needed many hints
- `intermediate` — completed milestones with some help, some fuzzy areas remain
- `advanced` — nailed milestones consistently, few or no struggles

Derive this from: nailed-it vs struggle ratio, sessions-taken vs sessions-estimated,
and whether fuzzy topics persist or get resolved across lessons.

**cross_topic_patterns:**
Themes that appear as struggles across two or more different lesson topics.
Example: "async patterns" struggled in both LangChain and LangGraph lessons.

### Graceful Handling

- If `insights.md` does not exist: skip it, derive what you can from archive and logs
- If archive and logs are empty (new user): return empty context, no errors
- If no patterns are detected: return empty context — don't manufacture insights

## Mode 2: Update Insights

Called by `/end-learn` after the session log and lesson state have been written.

### Input

The session's observations from the current conversation:
- Struggles (from the debrief's "Struggled with" section)
- Key learnings (from "Key learnings" section)
- Still fuzzy topics (from "Still fuzzy on" section)
- Hints given during the session

### Process

1. Read `~/.claude/learning/insights.md` (create it if it doesn't exist)
2. For each struggle theme from this session:
   - If it already exists in `## Recurring Struggles`: increment session count, update last-seen date
   - If it's new: add it with count 1
3. For each key learning from this session:
   - If the theme exists in `## Recurring Struggles` AND the user demonstrated
     clear understanding (nailed it, no hints needed): move it to `## Confirmed Strengths`
   - Otherwise: leave struggles as-is (one good session doesn't confirm mastery)
4. Update `## Difficulty Trend`:
   - Look at the gap addressed by the current lesson
   - If the session had mostly nailed-it observations: trend toward advanced
   - If the session had significant struggles: trend toward beginner
   - Use the overall pattern across sessions, not just this one session
5. If any incidental code observations were noted during the session,
   add them to `## Incidental Notes` with the lesson topic and date
6. Update `last_updated` in frontmatter

### User Notification

After updating, show the user a one-liner ONLY if something meaningful changed:
- A theme moved to confirmed strength: "Insight updated: [theme] moved to confirmed strength"
- A new recurring pattern detected (3+ sessions): "Pattern detected: [theme] has come up in N sessions now"
- Difficulty level changed for a gap: "Difficulty updated: [gap] progressed to [level]"

If nothing meaningful changed (just incremented a count, added a new single-occurrence
struggle), say nothing — don't create noise.

## Important

- This skill is NEVER called directly by users — only by `/learn` and `/end-learn`
- Build Context mode is READ-ONLY — it produces conversation context, writes nothing
- Update Insights mode writes ONLY to `insights.md` — no other files
- Do not read the repo — repo analysis is handled by `/learn` step 3.5
- Be conservative with "confirmed strength" promotion — require evidence across
  multiple sessions, not just one good moment
- Do not manufacture patterns from thin data — if there's only one session logged,
  there are no cross-topic patterns to report