lesson-learned
Analyze recent code changes via git history and extract software engineering lessons. Use when the user asks 'what is the lesson here?', 'what can I learn from this?', 'engineering takeaway', 'what did I just learn?', 'reflect on this code', or wants to extract principles from recent work.
Security Assessment
About lesson-learned
The lesson-learned skill is designed to analyze recent code changes from a git repository and extract actionable software engineering lessons. It solves the common problem of developers wanting to reflect on their work and gain insights from actual changes without relying on abstract or generic advice. Instead of providing theoretical guidance, this skill mirrors the code itself, highlighting what the code demonstrates in terms of principles, trade-offs, and structural decisions. By focusing on concrete examples, it helps engineers learn directly from their ongoing work, improving code quality and team practices over time.
The skill offers a structured, phased approach for analysis. It first determines the scope of changes, supporting feature branches, specific commits, the last N commits, or uncommitted working changes. Then, it gathers the relevant commit history and diffs, ensuring that large changes are filtered for manageable review. The analysis phase identifies dominant patterns, structural decisions, trade-offs, solved problems, and missed opportunities, mapping each observation to recognized software engineering principles. Lessons are presented in a clear, templated format, emphasizing the practical impact of the changes and providing actionable takeaways for future work. The skill also supports highlighting up to two additional noteworthy lessons while avoiding common pitfalls such as scope creep, ignoring commit messages, or providing overly negative feedback.
Use cases include reviewing recent work for self-reflection, extracting educational insights from team commits, and generating structured feedback for code review discussions. Target users are software engineers, team leads, and developers who want to internalize best practices directly from their code changes. It is particularly useful for developers who aim to continuously improve code quality, understand trade-offs, and integrate software engineering principles into their daily workflow, making learning from real work both practical and contextually grounded.
FAQ
How do I specify which code changes to analyze?
You can set the scope by indicating a feature branch, a specific commit, the last N commits, or your current working changes. If no scope is provided, the skill defaults to analyzing branch commits versus main or the last 5 commits on main.
Do I need to load any reference files before using the skill?
Yes, you must load `references/se-principles.md` to provide the catalog of principles. Optionally, you can load `references/anti-patterns.md` if you want to check for areas of improvement.
Can this skill analyze the entire repository?
No, it only analyzes the changes within the specified scope. It avoids reading the entire repository to focus on relevant code changes.
How does the skill present lessons?
Lessons are presented in a structured markdown template highlighting what happened in the code, the principle at work, why it matters, and a concrete takeaway for future work. Up to two additional lessons may be noted in a secondary section.
Are commit messages considered during analysis?
Yes, commit messages are treated as primary context because they often contain intent that the raw code diff does not convey.
Install lesson-learned
Quick Setup:
- Copy the skill folder to
.claude/skills/ - Claude will automatically detect and use the skill
Repository
softaworks/agent-toolkit