From lessons-learned
Use when the user asks about the lessons-learned plugin or wants to work with it. Use when the user wants to add a lesson, capture a coding mistake for future prevention, scan session logs for new lesson candidates, promote or archive candidates from the scan output, browse active lessons, or tune injection settings. Use when the user types /lessons:add, /lessons:review, /lessons:manage, /lessons:config, /lessons:doctor, /lessons:cancel, /lessons:scope, or /lessons:help. Use when the user asks what lessons are currently active, how to get started, how lesson injection works, what commands are available, or what has recently changed. Use when the user wants to audit or QA the lesson store for dead triggers, unreachable lessons, truncated summaries, or near-duplicates. Use when the user wants to retract or cancel a lesson tag they just emitted. Use when the user wants to find lessons that should only inject in the current project and scope them. Do not wait for the user to name this plugin explicitly — if they ask about capturing mistakes, lesson candidates, the scan-promote pipeline, or lesson injection into context, this skill applies.
How this skill is triggered — by the user, by Claude, or both
Slash command
/lessons-learned:lessons-learnedThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A Claude Code plugin that automatically captures coding mistakes from session logs and injects relevant warnings before the same mistake can happen again.
A Claude Code plugin that automatically captures coding mistakes from session logs and injects relevant warnings before the same mistake can happen again.
Session logs → scan → candidates (DB) → /lessons:review → active lessons
↓
lesson-manifest.json ← build
↓
Hook fires PreToolUse → injection
~/.claude/projects/ JSONL files for #lesson tags (structured) and error→correction patterns (heuristic). New patterns land in the DB as status='candidate'./lessons:review runs scan → LLM filter → conversational approval → batch promotion.lessons build compiles active lessons into lesson-manifest.json, the runtime index read by hooks.PreToolUse and SessionStart hooks match the manifest against the current tool call and prepend relevant lessons to Claude's context.candidate → reviewed → active → archived
↑ ↓
└── restore ─────────────┘
| Command | What it does |
|---|---|
/lessons:add | Conversationally add a lesson — Claude asks for problem, solution, trigger, then writes it |
/lessons:review | Scan for new candidates, LLM-filter them, present a numbered list, approve/archive → promote |
/lessons:manage | Browse and manage all lessons by status — promote, archive, edit, restore |
/lessons:config | View and tune configuration with plain-language explanations of every setting |
/lessons:doctor | QA audit — finds dead triggers, unreachable hints, guard false positives, truncated/long summaries, casing errors, near-duplicates. Offers automatic and interactive fixes. |
/lessons:cancel | Retract a lesson tag after the fact — archives DB records (any status) and emits #lesson:cancel markers for lessons emitted this session but not yet scanned. |
/lessons:scope | Scan active global lessons for ones that are project-specific (references project files, tools, or workflows), present each with reasoning, and scope approved ones to the current project. |
/lessons:help | Print the full command and config reference — all slash commands with descriptions, current config values, and what's been added or changed recently. |
Routine maintenance (weekly-ish)
/lessons:review
Scans, filters noise, presents candidates for approval.
Periodic QA (after bulk imports or edits)
/lessons:doctor
Audits 8 quality dimensions — dead triggers, unreachable hints, guard false positives, truncated summaries, casing errors, near-duplicates. Applies mechanical fixes automatically, reviews judgment calls interactively.
Scope project-specific lessons (after bulk imports or cross-project work)
/lessons:scope
Scans all active global lessons, flags ones that reference this project's files or workflows, presents each with evidence, and scopes approved ones to the current project only.
Retract a lesson you just emitted
/lessons:cancel
Shows recently emitted lessons (DB + unscanned this session), lets you pick which to retract. Emits #lesson:cancel markers for unscanned ones so the scanner skips them.
Quick manual capture
/lessons:add
Claude asks 5 questions and writes the lesson. ~2 minutes.
Tune what gets injected
/lessons:config
Adjust maxLessonsPerInjection, minConfidence, injectionBudgetBytes.
Fix or retire a lesson
/lessons:manage
→ "edit priority on pytest-tty-hanging"
→ "archive git-stash-untracked — superseded"
Load these when you need deeper detail — don't load all of them upfront:
| File | Load when... |
|---|---|
references/lesson-fields.md | User asks about a specific field, or you're building a lesson JSON payload |
references/writing-guide.md | User is adding a lesson manually, or you're enriching candidates during review |
references/lesson-emission.md | User asks about the #lesson tag format, or you need to emit a lesson after a mistake |
references/cli-reference.md | User asks about CLI subcommands or you need a specific flag |
references/data-files.md | User asks about data directory contents or file purposes |
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub joeblackwaslike/agent-marketplace --plugin lessons-learned