Guide · Agent skill
How to use the Explain How and Why agent skill (ce-explain)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The ce-explain skill is an agent skill for Claude that explains why a project works the way it does, or what happened over a stretch of work, using evidence from the source rather than guesses. It is useful for developers learning an unfamiliar codebase, team leads who want a recap of recent changes, and anyone preparing a teaching document. By the end of this guide you will know what the skill does, how to install it, how to phrase requests that trigger it, and what to check before relying on its output.
Explain How and WhyEveryInc/compound-engineering-plugin · MIT Download the skill Quick start
- 1Download the ZIP. Download the ce-explain skill ZIP from this page.
- 2Unzip into a skills folder. Unzip into ~/.claude/skills/ for personal use, or into .claude/skills/ in a project.
- 3Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.
- 4Ask for an explanation. Describe the code, change, or time window you want explained and who will read it.
- 5Review the evidence and unknowns. Check the cited evidence and the list of unknowns in the result.
- 6Use the artifact if requested. If you asked for a file, open the explainer and its location that the agent reports.
What the ce-explain skill makes the agent do
When you ask why something in a project has its current shape, or what happened over a window of work, this skill tells the agent to gather evidence from the source and produce a grounded explanation. The agent separates documented rationale from its own inference and lists what remains unknown.
The skill can also produce a standalone explainer document, and it can dispatch helper subagents to trace how behavior actually runs or to recap a window of activity.
- Explains the current design of code, grounded in source evidence.
- Separates documented rationale, the agent's inference, and unknowns.
- Can recap a window of work, such as recent commits and pull requests when those are reachable.
- Can write a standalone explainer file in HTML or Markdown.
Install the ce-explain skill
Download the ZIP for the skill from this page. Then choose one of two ways to install it, depending on whether you want it available everywhere or only in one project.
For a personal install across projects, unzip the download into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Trigger the skill with natural requests
You do not need a special command. The skill's description tells the agent to use it when you ask for an explanation. Describe the thing you want explained and, if it matters, who will read the answer.
If you want a judgment or recommendation instead, ask for that directly. The skill itself says those requests belong to a different skill, ce-pov.
- Why does the retry logic in this project work the way it does?
- Explain how the billing module got its current structure and what decisions shaped it.
- Recap what changed in this repo over the last two weeks for my team lead.
- Write a teaching document explaining the auth flow for new developers.
What the skill needs
The skill needs access to a Git repository so it can locate the repo root and read history. An optional config file at .compound-engineering/config.yaml can set where explainer artifacts are stored. The skill writes scratch evidence to /tmp directories during a run.
The skill runs scripts. It does not use the network, according to the listing.
- Git repository access
- Optional: .compound-engineering/config.yaml for artifact location
- Scratch space in /tmp for run evidence
- Runs scripts: yes. Uses network: no.
Safety notes on scripts and file writes
Because the skill runs scripts and writes to /tmp, review the files you install before you rely on them, as you would with any skill. The skill's own instructions say the scratch directory is created with restricted permissions and rejects symlinks or directories owned by another user.
The skill's scouts are told not to modify the repository while tracing behavior.
- Read the SKILL.md and reference files before installing into a shared project.
- Expect scratch files under a run directory in /tmp.
- Explainers are written only when an artifact is requested.
Tips for getting reliable explanations
Name the specific thing you want explained and, where possible, the time window. Say who the reader is, because the skill adapts depth to the intended audience.
Treat the output as a guide to verify, not a final authority. The skill can still miss implementation details it did not inspect, so check claims that matter before acting on them.
- Give a specific subject, such as a module, change, or time window.
- State the intended use or reader.
- Check the listed unknowns before making high-stakes decisions.
What people use it for
- Understanding an unfamiliar codebase by asking why a module is structured the way it is.
- Finding out what past design decisions shaped a feature.
- Giving a team lead a grounded recap of recent changes over a set window.
- Preparing a teaching document to walk colleagues through how a system behaves.
Frequently asked questions
How do I install the ce-explain skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.
Is ce-explain free to use?
The skill is listed under the MIT licence. This page does not state pricing for any other service, so check the licence file in the repository for the terms.
What does ce-explain require?
It requires Git repository access to locate the repo root. An optional .compound-engineering/config.yaml file can set artifact location, and it writes scratch evidence to /tmp during runs. It runs scripts and does not use the network.
What is the difference between ce-explain and ce-pov?
ce-explain explains how and why something is shaped as it is, or what happened over a window of work. The skill's description says to use ce-pov for a judgment or recommendation.
Why did the agent say some rationale is unknown?
The skill separates documented rationale from inference and lists unknowns. If the repository does not record why a decision was made, the agent should say so rather than invent a reason.
Can I trust the explanation for a high-stakes decision?
Not without human review. The agent may miss implementation details it did not inspect, so verify important claims against the source before acting on them.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use ce-explain if you want evidence-backed explanations of an unfamiliar codebase, a grounded recap of recent work, or a teaching document for colleagues. Pick ce-pov or a human reviewer when you need a recommendation or a decision that must be fully accurate.
Download the skill