| name | claude-learn |
| description | Master skill for the reflect->capture->distribute learning loop in any repository: its MAIN TASK is to reflect on a session/task and turn what it taught into durable, reusable knowledge, then distribute it. Reflect on what a session revealed, capture it by authoring/updating skills, agents, docs, and a lessons file, and distribute it both to the team (repo-local `.claude/skills/`, committed) and across projects (global `~/.claude/skills/`) via push learnings up, pull skills down, or reconcile, all through the bundled skill-sync leaf. Delegates each step to the correct leaf skill. Triggers on: "reflect", "review session", "what did we do", "session summary", "learnings", "capture lessons", "update lessons", "improve skills", "update docs", "analyze conversation", "learning loop", "create skill", "update skill", "new skill", "write a skill", "global skill", "promote skill", "sync skills", "reconcile skills", "pull global skill", "skills out of sync", "drift audit", "skill drift". |
| license | CC-BY-NC-SA-4.0 |
claude-learn — Reflect on the work, turn it into durable knowledge
The main task: reflect on what a session/task actually taught, and turn it into durable, reusable knowledge. A pattern proven, a gotcha hit, a convention settled: capture it so the next person (human or agent) starts from it instead of rediscovering it. That knowledge lives in skills, agents, docs, and a lessons file, and is distributed two ways: to the team (repo-local, committed) and across your own projects (global). Everything this router does serves that one loop:
Reflect -> Capture -> Distribute.
Reflect on the session (what worked, what broke, what is now known) -> Capture it by authoring/updating a skill, an agent, a doc, or a lessons entry -> Distribute it by syncing local <-> global (push learnings up to global, pull skills down to the repo for the team).
Route the heavy lifting to the leaf that owns each step; do not do it inline. Reflection/analysis, doc distribution, skill authoring, and pull/push syncing are all first-class steps of the loop, and any one of them (for example a standalone "sync my skills" or "reflect on this session") is a valid entry point.
This skill is repo-independent: it names no project-specific paths, agents, or conventions. Anything that is specific to one repository belongs in that repo's CLAUDE.md, not here.
When to Use This Skill
- After a work session, to capture what it taught and record it in the repo's lessons file
- After a correction from the user, to write a rule that prevents the same mistake
- After a structural change to the repo, to distribute the update to every file that references it
- When a session revealed a reusable rule/convention/gotcha that belongs in a skill (create or update a skill, local or global)
- When skills need reconciling local <-> global, after authoring skill edits or as a standalone "sync my skills" request
- When the user says "reflect", "what did we learn", "update docs", "create/update a skill", or "sync/reconcile skills"
Trigger keywords: reflect, review session, learnings, capture lessons, analyze conversation, learning loop, update docs, what did we do, improve skills, create skill, update skill, new skill, write a skill, global skill, promote skill, sync skills, reconcile skills, pull global skill, skills out of sync
First use in a repo
The analyze leaf can read a rich session record when the repo wires session-tracking hooks. This is optional: on the live session you already hold the context and can reflect directly. If the user wants persistent cross-session tracking and it is not wired yet, run claude-learn-setup once; otherwise skip it.
Delegate Map
| Request type | Leaf skill to invoke |
|---|
| Analyze a session for patterns, mistakes, and learnings; write them to the lessons file | claude-analyze |
Distribute an update across the docs, skills, agents, and CLAUDE.md that reference it | claude-learn-distribute |
| Create or update a skill (local or global) from a learning | claude-learn-distribute — "Creating & updating skills" section |
| Push learnings up (local -> global, additive) | skill-sync — "Push learnings" |
| Pull skills down (global -> local, for the team) | skill-sync — "Pull skills" |
| Two-way reconcile a skill local <-> global (best-of-both) | skill-sync — "Reconcile" |
| Report which skills are out of sync (read-only) | skill-sync — "List / status" |
| Bulk-reconcile a broadly drifted skill / periodic drift audit | skill-drift-audit |
| First use in a repo without session tracking wired | claude-learn-setup |
Run analyze first. Its findings feed the distribute leaf, which decides which docs, skills, and agents to touch. Skill files (local and global) are created/updated per the skill-authoring workflow in the distribute leaf; the local <-> global reconciliation is then routed to the matching sync skill above, which is the loop's final step, not optional.
Syncing skills (local <-> global) — a main task
The two tiers, and why both exist:
| Tier | What it is | Shared how |
|---|
Local — <repo>/.claude/skills/ | The team-shared, git-committed copy. Teammates get skills by pulling the repo. | Via git (commit local skill changes) |
Global — ~/.claude/skills/ | Your personal, cross-project library. Not git-tracked, one machine. | Only to you, across all your repos |
We keep skills in the repo (local), not global-only, precisely because others work on the repo: a global-only skill is invisible to teammates. So the two operations are:
- Pull skills (global -> local): bring a proven skill from your personal library down into the repo so the team gets it (then commit). This is how a pattern proven elsewhere lands here for everyone.
- Push learnings (local -> global): promote what this session taught up to your personal library so your other repos benefit.
Both directions (plus two-way reconcile and read-only status) are owned by the skill-sync leaf; route there, never hand-copy skill trees. Local skill edits are the team's artifact: leave them staged in the working tree for the user to commit (per the never-auto-commit rule).
Sync the whole skill, not just SKILL.md — every subskill counts. A skill's value is the full proven pattern; the manifest is only a router and the detail lives in references/*.md. Syncing must be recursive over the entire skill folder: diff recursively (diff -rq <global> <local>), union one-sided files so no detail is lost, and resolve two-sided differences per file. A brand-new local skill with no global counterpart is a prime Push candidate, not something to skip. Always run the hygiene gate after authoring, before syncing: bash ~/.claude/scripts/lint-claude-config.sh <repo>.
Example Prompts
- "Reflect on this session and capture the learnings in the lessons file."
- "Review the last 2 sessions in
~/.claude/projects/<project>/ for recurring mistakes."
- "Distribute the folder restructure to every doc and skill that references the old paths."
- "We renamed a skill; sync
CLAUDE.md and run the config lint."
- "Turn the Windows git-mv file-lock fix into a skill so other repos get it too."
- "Sync my skills local <-> global." / "Which skills are out of sync with global?"
