Capture lessons

Skill MaxLiuyy/Claude-Code-Skills/capture-lessons

Some Claude Code skills created and used myself.

Install

npx -y skills add MaxLiuyy/Claude-Code-Skills --skill capture-lessons

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Summarize the current conversation and implementation into a durable lessons note saved under the project's lessons directory. Use when the user asks to capture lessons learned, save takeaways, record gotchas, write a retrospective, preserve decisions or fixes from the current session, or update a lessons log. Resolve the destination by reading AGENTS.md or CLAUDE.md for an explicit lessons path; if none is declared, prefer `.agents/lessons/`, then `.claude/lessons/`.

SKILL.md

4.2 KB, as published. Nobody here has run it

Capture Lessons

Turn the current session into a concise markdown note that future agents can reuse. Capture only the parts that would save time later: constraints, root causes, decisions, commands, and file-level evidence.

Workflow

Review the current conversation and the files that matter.

Prefer concrete evidence from code, configs, and command results.
Ignore routine back-and-forth unless it explains a non-obvious decision.

Decide what is worth keeping.

Keep root causes, fixes, decision rationale, reusable commands, and repo-specific constraints.
Skip raw transcript content, generic advice, and dead ends that add no future value.

Draft a short note before writing anything.

Use a specific title tied to the problem or decision.
Keep the note scannable and reuse-oriented.
Prefer this structure:

# <title>

## Context

## Lessons
- <lesson>

## Evidence

## Affected Files
- [path](/absolute/path)

## Open Questions

Resolve the output directory and save the note.

Run python3 scripts/save_lesson.py --workspace <repo> --title "<title>" --content-file <tmp-markdown-file>.
The script searches upward from --workspace.
In each directory, it checks AGENTS.md before CLAUDE.md.
It accepts explicit declarations such as LESSONS_DIR: Lessons, lessons folder: docs/lessons, save lessons to: .agents/lessons/, or save lessons to: .claude/lessons/.
If no declaration is found, it reuses .agents/lessons/ when present, otherwise .claude/lessons/ when present, otherwise creates .agents/lessons/ under the workspace root.

Re-open the written file and verify quality.

Every lesson should be actionable or explanatory.
The note should be shorter and cleaner than the original conversation.
Keep filenames stable and descriptive; let the script append a numeric suffix if the slug already exists.

Destination Rules

Support absolute or relative paths declared in AGENTS.md or CLAUDE.md.
Resolve relative paths from the directory containing the declaration file.
Prefer the nearest declaration to the current workspace.
Fall back in this order when no declaration exists: .agents/lessons/, then .claude/lessons/ if it already exists.

Supported Declarations

The bundled script recognizes these common forms:

LESSONS_DIR: Lessons
LESSONS_PATH = docs/lessons
- lessons folder: .agents/lessons/
- lessons folder: .claude/lessons/
- lessons directory: docs/lessons
- save lessons to: docs/retros

Keep declarations simple: one path per line. The helper also tolerates legacy values joined with or, but new declarations should stay single-path.

Content Bar

Good lesson notes usually include:

Why something failed or succeeded.
Constraints that are easy to miss on a fresh read.
Commands, paths, or patterns worth reusing.
Evidence pointing to the changed files or configs.

Weak lesson notes usually include:

Generic best practices.
Raw transcript snippets.
Status updates with no reusable insight.
Exhaustive implementation detail with no future decision value.

Script Reference

Use the bundled helper from this skill directory:

python3 scripts/save_lesson.py --workspace "$PWD" --print-dir
python3 scripts/save_lesson.py --workspace "$PWD" --title "fix data loader race" --content-file /tmp/lesson.md

Arguments:

--workspace: repository or working directory to resolve against.
--title: optional note title; if omitted, the first markdown H1 is used.
--content-file: read the lesson body from a markdown file. If omitted, read from stdin.
--print-dir: print the resolved lessons directory without writing a note.
--dry-run: print the resolved output path without writing the file.