explain-like_skill

Overview

This skill explains code changes or design documents at three progressive expertise levels: beginner, intermediate, and expert. It helps reviewers and authors quickly grasp what changed, why it matters, and where gaps or risks live. Use it to validate PRs, branches, or design drafts and to create clear, multi-audience documentation.

How this skill works

When invoked, the skill gathers the subject: diffs and commits for a branch/PR or the specified design file. It then produces three structured explanations that follow the same template (What/Why/Key concepts for beginner; Changes/Implementation/Trade-offs for intermediate; Deep dive/Architecture/Potential issues for expert). For design validation it adds a findings section listing gaps, logic issues, questions, and recommendations. Optionally it can save the output to a recommended specs path after user confirmation.

When to use it

• After finishing a feature branch or PR to summarize and validate changes
• When drafting or reviewing a design doc to surface missing assumptions
• Before code review to create a clear, audience-tailored explanation
• When onboarding teammates or creating handoff documentation
• To audit architectural implications and hidden failure modes

Best practices

• Always include the base branch or design file path so diffs are accurate
• Generate all three levels every time — beginner explanations reveal assumed knowledge
• Highlight files/components changed and key commits in the intermediate level
• List concrete gaps and recommendations during design validation
• Ask for permission before writing explanations back into the repo

Example use cases

• "Explain this PR" — produce beginner/intermediate/expert summaries and risk list for reviewers
• "Validate this design" — read a design doc, explain at three levels, and output validation findings
• "Explain like I'm a beginner" — create an accessible summary for non-engineers or new hires
• Create a specs/explanation.md for a feature after approval, with a clear record for future maintainers
• Use expert-level output to identify performance and integration concerns before deployment