{"id":"2e04bcd6-db7c-4122-a24b-13b8708e4828","shortId":"dqFsz6","kind":"skill","title":"lesson-learned","tagline":"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 re","description":"# Lesson Learned\n\nExtract specific, grounded software engineering lessons from actual code changes. Not a lecture -- a mirror. Show the user what their code already demonstrates.\n\n## Before You Begin\n\n**Load the principles reference first.**\n\n1. Read `references/se-principles.md` to have the principle catalog available\n2. Optionally read `references/anti-patterns.md` if you suspect the changes include areas for improvement\n3. Determine the scope of analysis (see Phase 1)\n\n**Do not proceed until you've loaded at least `se-principles.md`.**\n\n## Phase 1: Determine Scope\n\nAsk the user or infer from context what to analyze.\n\n| Scope | Git Commands | When to Use |\n|-------|-------------|-------------|\n| Feature branch | `git log main..HEAD --oneline` + `git diff main...HEAD` | User is on a non-main branch (default) |\n| Last N commits | `git log --oneline -N` + `git diff HEAD~N..HEAD` | User specifies a range, or on main (default N=5) |\n| Specific commit | `git show <sha>` | User references a specific commit |\n| Working changes | `git diff` + `git diff --cached` | User says \"what about these changes?\" before committing |\n\n**Default behavior:**\n- If on a feature branch: analyze branch commits vs main\n- If on main: analyze the last 5 commits\n- If the user provides a different scope, use that\n\n## Phase 2: Gather Changes\n\n1. Run `git log` with the determined scope to get the commit list and messages\n2. Run `git diff` for the full diff of the scope\n3. If the diff is large (>500 lines), use `git diff --stat` first, then selectively read the top 3-5 most-changed files\n4. **Read commit messages carefully** -- they contain intent that raw diffs miss\n5. Only read changed files. Do not read the entire repo.\n\n## Phase 3: Analyze\n\nIdentify the **dominant pattern** -- the single most instructive thing about these changes.\n\nLook for:\n- **Structural decisions** -- How was the code organized? Why those boundaries?\n- **Trade-offs made** -- What was gained vs. sacrificed? (readability vs. performance, DRY vs. clarity, speed vs. correctness)\n- **Problems solved** -- What was the before/after? What made the \"after\" better?\n- **Missed opportunities** -- Where could the code improve? (present gently as \"next time, consider...\")\n\nMap findings to specific principles from `references/se-principles.md`. Be specific -- quote actual code, reference actual file names and line changes.\n\n## Phase 4: Present the Lesson\n\nUse this template:\n\n```markdown\n## Lesson: [Principle Name]\n\n**What happened in the code:**\n[2-3 sentences describing the specific change, referencing files and commits]\n\n**The principle at work:**\n[1-2 sentences explaining the SE principle]\n\n**Why it matters:**\n[1-2 sentences on the practical consequence -- what would go wrong without this, or what goes right because of it]\n\n**Takeaway for next time:**\n[One concrete, actionable sentence the user can apply to future work]\n```\n\nIf there is a second lesson worth noting (maximum 2 additional):\n\n```markdown\n---\n\n### Also worth noting: [Principle Name]\n\n**In the code:** [1 sentence]\n**The principle:** [1 sentence]\n**Takeaway:** [1 sentence]\n```\n\n## What NOT to Do\n\n| Avoid | Why | Instead |\n|-------|-----|---------|\n| Listing every principle that vaguely applies | Overwhelming and generic | Pick the 1-2 most relevant |\n| Analyzing files that were not changed | Scope creep | Stick to the diff |\n| Ignoring commit messages | They contain intent that diffs miss | Read them as primary context |\n| Abstract advice disconnected from the code | Not actionable | Always reference specific files/lines |\n| Negative-only feedback | Demoralizing | Lead with what works, then suggest improvements |\n| More than 3 lessons | Dilutes the insight | One well-grounded lesson beats seven vague ones |\n\n## Conversation Style\n\n- **Reflective, not prescriptive.** Use the user's own code as primary evidence.\n- **Never say \"you should have...\"** -- instead use \"the approach here shows...\" or \"next time you face this, consider...\"\n- **If the code is good, say so.** Not every lesson is about what went wrong. Recognizing good patterns reinforces them.\n- **If the changes are trivial** (a single config tweak, a typo fix), say so honestly rather than forcing a lesson. \"These changes are straightforward -- no deep lesson here, just good housekeeping.\"\n- **Be specific.** Generic advice is worthless. Every claim must point to a concrete code change.","tags":["lesson","learned","agent","toolkit","softaworks","agent-skills","automation","claude","claude-code","coding-agent","development"],"capabilities":["skill","source-softaworks","skill-lesson-learned","topic-agent-skills","topic-automation","topic-claude","topic-claude-code","topic-coding-agent","topic-development"],"categories":["agent-toolkit"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/softaworks/agent-toolkit/lesson-learned","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add softaworks/agent-toolkit","source_repo":"https://github.com/softaworks/agent-toolkit","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 1847 github stars · SKILL.md body (4,412 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:52:57.955Z","embedding":null,"createdAt":"2026-04-18T20:28:32.308Z","updatedAt":"2026-05-18T18:52:57.955Z","lastSeenAt":"2026-05-18T18:52:57.955Z","tsv":"'-2':437,447,529 '-3':422 '-5':288 '1':83,113,125,243,436,446,501,505,508,528 '2':92,240,258,421,490 '3':105,269,287,317,584 '4':293,405 '5':185,228,305 '500':275 'abstract':558 'action':472,565 'actual':59,395,398 'addit':491 'advic':559,684 'alreadi':73 'also':493 'alway':566 'analysi':110 'analyz':4,137,217,225,318,532 'appli':477,522 'approach':620 'area':102 'ask':20,128 'avail':91 'avoid':514 'beat':594 'before/after':366 'begin':77 'behavior':211 'better':371 'boundari':342 'branch':145,162,216,218 'cach':201 'care':297 'catalog':90 'chang':7,61,100,196,207,242,291,308,330,403,427,537,652,671,695 'claim':688 'clariti':357 'code':6,42,60,72,338,377,396,420,500,563,608,632,694 'command':140 'commit':166,187,194,209,219,229,254,295,431,545 'concret':471,693 'config':657 'consequ':452 'consid':384,629 'contain':299,548 'context':134,557 'convers':598 'correct':360 'could':375 'creep':539 'decis':334 'deep':675 'default':163,183,210 'demonstr':74 'demor':574 'describ':424 'determin':106,126,249 'diff':152,172,198,200,261,265,272,279,303,543,551 'differ':235 'dilut':586 'disconnect':560 'domin':321 'dri':355 'engin':14,32,56 'entir':314 'everi':518,638,687 'evid':611 'explain':439 'extract':12,46,52 'face':627 'featur':144,215 'feedback':573 'file':292,309,399,429,533 'files/lines':569 'find':386 'first':82,281 'fix':661 'forc':667 'full':264 'futur':479 'gain':349 'gather':241 'generic':525,683 'gentl':380 'get':252 'git':9,139,146,151,167,171,188,197,199,245,260,278 'go':455 'goe':461 'good':634,646,679 'ground':54,592 'happen':417 'head':149,154,173,175 'histori':10 'honest':664 'housekeep':680 'identifi':319 'ignor':544 'improv':104,378,581 'includ':101 'infer':132 'insight':588 'instead':516,617 'instruct':326 'intent':300,549 'larg':274 'last':164,227 'lead':575 'learn':3,29,38,51 'least':122 'lectur':64 'lesson':2,15,24,50,57,408,413,486,585,593,639,669,676 'lesson-learn':1 'line':276,402 'list':255,517 'load':78,120 'log':147,168,246 'look':331 'made':346,368 'main':148,153,161,182,221,224 'map':385 'markdown':412,492 'matter':445 'maximum':489 'messag':257,296,546 'mirror':66 'miss':304,372,552 'most-chang':289 'must':689 'n':165,170,184 'name':400,415,497 'negat':571 'negative-on':570 'never':612 'next':382,468,624 'non':160 'non-main':159 'note':488,495 'off':345 'one':470,589,597 'onelin':150,169 'opportun':373 'option':93 'organ':339 'overwhelm':523 'pattern':322,647 'perform':354 'phase':112,124,239,316,404 'pick':526 'point':690 'practic':451 'prescript':602 'present':379,406 'primari':556,610 'principl':47,80,89,389,414,433,442,496,504,519 'problem':361 'proceed':116 'provid':233 'quot':394 'rang':179 'rather':665 'raw':302 're':49 'read':84,94,284,294,307,312,553 'readabl':352 'recent':5 'recogn':645 'refer':81,191,397,567 'referenc':428 'references/anti-patterns.md':95 'references/se-principles.md':85,391 'reflect':39,600 'reinforc':648 'relev':531 'repo':315 'right':462 'run':244,259 'sacrif':351 'say':203,613,635,662 'scope':108,127,138,236,250,268,538 'se':441 'se-principles.md':123 'second':485 'see':111 'select':283 'sentenc':423,438,448,473,502,506,509 'seven':595 'show':67,189,622 'singl':324,656 'skill' 'skill-lesson-learned' 'softwar':13,55 'solv':362 'source-softaworks' 'specif':53,186,193,388,393,426,568,682 'specifi':177 'speed':358 'stat':280 'stick':540 'straightforward':673 'structur':333 'style':599 'suggest':580 'suspect':98 'takeaway':33,466,507 'templat':411 'thing':327 'time':383,469,625 'top':286 'topic-agent-skills' 'topic-automation' 'topic-claude' 'topic-claude-code' 'topic-coding-agent' 'topic-development' 'trade':344 'trade-off':343 'trivial':654 'tweak':658 'typo':660 'use':16,143,237,277,409,603,618 'user':19,69,130,155,176,190,202,232,475,605 'vagu':521,596 've':119 'via':8 'vs':220,350,353,356,359 'want':44 'well':591 'well-ground':590 'went':643 'without':457 'work':195,435,480,578 'worth':487,494 'worthless':686 'would':454 'wrong':456,644 '~n':174","prices":[{"id":"935581be-5118-4615-82c9-c330bb42d0cb","listingId":"2e04bcd6-db7c-4122-a24b-13b8708e4828","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"softaworks","category":"agent-toolkit","install_from":"skills.sh"},"createdAt":"2026-04-18T20:28:32.308Z"}],"sources":[{"listingId":"2e04bcd6-db7c-4122-a24b-13b8708e4828","source":"github","sourceId":"softaworks/agent-toolkit/lesson-learned","sourceUrl":"https://github.com/softaworks/agent-toolkit/tree/main/skills/lesson-learned","isPrimary":false,"firstSeenAt":"2026-04-18T21:54:36.183Z","lastSeenAt":"2026-05-18T18:52:57.955Z"},{"listingId":"2e04bcd6-db7c-4122-a24b-13b8708e4828","source":"skills_sh","sourceId":"softaworks/agent-toolkit/lesson-learned","sourceUrl":"https://skills.sh/softaworks/agent-toolkit/lesson-learned","isPrimary":true,"firstSeenAt":"2026-04-18T20:28:32.308Z","lastSeenAt":"2026-05-07T22:40:55.563Z"}],"details":{"listingId":"2e04bcd6-db7c-4122-a24b-13b8708e4828","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"softaworks","slug":"lesson-learned","github":{"repo":"softaworks/agent-toolkit","stars":1847,"topics":["agent-skills","ai","automation","claude","claude-code","coding-agent","development"],"license":"mit","html_url":"https://github.com/softaworks/agent-toolkit","pushed_at":"2026-03-05T16:46:24Z","description":"A curated collection of skills for AI coding agents. Skills are packaged instructions and scripts that extend agent capabilities across development, documentation, planning, and professional workflows.","skill_md_sha":"e358582cc398ba0c02b9a2cc2ae13b29d3e6ba59","skill_md_path":"skills/lesson-learned/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/softaworks/agent-toolkit/tree/main/skills/lesson-learned"},"layout":"multi","source":"github","category":"agent-toolkit","frontmatter":{"name":"lesson-learned","description":"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."},"skills_sh_url":"https://skills.sh/softaworks/agent-toolkit/lesson-learned"},"updatedAt":"2026-05-18T18:52:57.955Z"}}