English | Tiếng Việt
If you ask an AI to explain the code it just wrote and you walk away still confused, that is on the AI, not you. By default, models dump walls of jargon, skip the mental model, and throw unfamiliar APIs or library mechanisms at you without saying when they run or what they return.
learn-from-code is an Agent Skill that fixes how your coding agent explains git diffs and commits. When an agent writes a large change across several files, this skill makes it start with plain-language concepts, explain unfamiliar APIs and mechanisms before showing code, and walk through concrete test cases step by step.
Install with the Skills CLI (works with Claude Code, Cursor, Antigravity, OpenCode, Codex, Windsurf, Cline, and 70+ agents):
# Install in current project
npx skills add HarleySw/learn-from-code-skill
# Or install globally
npx skills add -g HarleySw/learn-from-code-skillManual installation
Copy skills/learn-from-code/SKILL.md into your agent's skill or rules folder:
- Claude Code:
.claude/skills/learn-from-code/SKILL.md - Cursor:
.cursor/rules/learn-from-code.mdc - Google Antigravity / OpenCode / Codex:
.agents/skills/learn-from-code/SKILL.md
To review a commit, git diff, or existing module (Mode A, default):
/learn-from-code
/learn-from-code explain commit 0bb8705
To practice writing the core logic yourself while the agent sets up the surrounding boilerplate (Mode B, TODO(human)):
Use learn-from-code in Mode B to implement the retry backoff logic.
In Mode A, the review runs in two turns so you can check your understanding before moving on.
Turn 1: Understand the change
- Big picture: Describes what happens in practice, why the bug or design problem occurs using an everyday analogy, and a short
Before -> Aftersnippet (❌vs✅) without burying you in file or variable names upfront. - Main execution flow: Traces the path from the user action or system trigger through the main functions or entry points (at most one primary function or mechanism per step).
- Core code steps: Explains unfamiliar APIs, library mechanisms, or parameters before showing the code block, adds inline comments and concrete examples above each branch, explains why simpler approaches fail, and walks through concrete cases (with
< 76-charASCII rulers when string slicing or offsets are involved). - Verification & hidden risks: Checks callers outside the
git diff, backward compatibility with saved data, and edge cases. If the diff has a bug, it flags it under⚠️ Defect Alertwith a❌ Current -> ✅ Fixsnippet. - Debugging check: Ends with boundary scenarios and a small code slice right in place, so you can test your mental model without scrolling back up.
Turn 2: Consolidate & level up (after you reply)
- Detailed answer review: Confirms correct answers concisely in 1–2 sentences, and unpacks missed edge cases or proposed fixes with
< 76-charcode slices and step-by-step traces at exactfilename:linereferences. - Reusable techniques for other projects: Extracts every worthwhile engineering pattern from the diff with a domain-independent code template, when to apply it, and when it breaks down.
- Architectural critique & senior takeaways: Compares tactical patches against cleaner root-level designs (
❌ Current patchvs✅ Root-level design), highlights hidden coupling traps (Single Source of Truth), and exposes why existing unit tests stayed green despite edge-case bugs.
The output is formatted to fit both 80-column CLI terminals and narrow IDE chat sidebars. Code comments and ASCII diagrams stay under 76 characters per line, explanations use short sub-bullets (1 idea = 1 bullet), and domain codes are checked against your repo's docs and tests before the agent explains them.
It also responds in whatever language you use (English, Vietnamese, Japanese, and others) while keeping everyday developer terms (git diff, commit, race condition, fallback, callback, unit test) intact.
MIT © HarleySw