What and Why of explain-it

You ask Claude to review a repo you barely know. It comes back with 30 findings : critical, high, medium, low.

Now what?

You can't evaluate any of them. Not because the findings are bad, but because you don't have the mental model yet.

Finding #7 says a config blob gets re-read on every request. Is that bad? Depends on how big the blob is, how often that endpoint gets hit, whether there's a cache sitting in front of it. All things the repo knows and you don't.

So you end up three files deep in a codebase you've never seen, trying to work out whether the agent found a real problem or is just pattern-matching.

That was my week. So I built a skill for it.

What it is

explain-it — point your agent at a review, a PR, or a subsystem, and instead of a wall of findings you get a small static HTML site.

Here's what's inside it.

A primer page. The 2-minute mental model of the system, before any findings. What the moving pieces are, one plain metaphor each. You read this first, and suddenly the findings have somewhere to land.

One page per topic. Each one opens with "when does this code even run?" — a real trace. User does X, system calls Y, and this function sits inside it. Then the current state of the code. Then the proposed diff, red/green, trimmed to the crux, with inline comments explaining why, not narrating what changed.

Quantified stakes. Not "this is slow." Instead : hundreds of KB per request, ~99% of the time for nothing. That's the difference between a finding you can act on and one you can only nod at.

Bugs separated from decisions. Half of what a review flags isn't a defect, it's a trade-off someone made on purpose. Those get presented as decisions with the trade-off stated, not as mistakes.

A scoreboard at the end. Every item marked done, proposed, or parked, and where it lives in the codebase.

Why plain HTML

It's plain HTML files. CSS inline, no build step, no router. Opens straight from disk, works offline, still works in five years.

That last part matters more than it sounds. An explainer that needs npm install to read is an explainer nobody reads. You should be able to zip the folder, email it, and have it open on the other side.

The bar

The bar I was aiming for, and the whole reason this exists : simple language that is not too simple and not too difficult. Never talk down, never assume repo knowledge.

The reader model is a smart engineer who has never seen this codebase. They can follow any concept you explain to them. They can follow exactly zero concepts you don't. Every rule in the skill falls out of that one sentence — the metaphor discipline, the runtime stories, the ban on words like "slow" and "big" and "sometimes."

Using it

Install it with the skills CLI :

npx skills add ankitvashisht12/explain-it --skill explain-it

Then ask your agent for it in plain language :

"Explain this PR in simple terms — I have no context of this code."

"Create an explainer site for the auth subsystem for new hires."

"Turn these review findings into a walkthrough my cofounder can read."

The agent reads the actual code first — the changed lines, the enclosing function, at least one caller — so the runtime stories are true and not invented. Then it plans the pages and builds them from the bundled template.

MIT licensed. Works with Claude Code, Codex, Cursor, and anything else that reads Agent Skills — the source is on GitHub.

Reviews will keep getting cheaper to generate. Understanding them won't. This is my small bet on the second half.

I hope you find this article interesting. Thanks for reading. Until then, bye 👋