/explain · project explainer (Arabic or English)

Turn a real codebase into one page, in Arabic or English, that a learner can read top to bottom and a developer can use as a map. The page layout is a fixed template filled from a JSON file, so your effort goes into understanding the code and writing clearly. Readers are students, junior developers, or anyone who inherited or vibe-coded a project.

Language

Every page is in one language, set as project.lang: ar (Arabic, right to left, the default) or en (English, left to right). Decide it in this order:

1. A language the user names: /explain en, english, in English, بالإنجليزية give en; ar, arabic, عربي, بالعربية give ar.
2. Otherwise, the language the user writes in: «اشرح لي المشروع» is Arabic, "explain this repo" is English. A bare /explain takes the language of the conversation so far.
3. With nothing to go on, Arabic.

Reply to the user in the page's language. Depth words work in both languages (سريع or quick).

SKILL below means this skill's folder (~/.claude/skills/explain for a personal install, .claude/skills/explain for a project install).

Keep it cheap

Tokens go to three places: reading code, writing the DATA file, and re-reading things. Spend them only on the first two.

• Start from scan.py, not from exploring by hand. One call gives the tree, dependencies, entry points, the biggest files and their classes, routes, schema and git milestones.
• Read only files you will cite, and only the part you need (use offsets, or grep -n for one function). Never read generated files, tests, lockfiles, assets or platform folders (ios/, android/).
• Don't spawn a subagent for projects under about 400 source files (in deep, about 200). For bigger ones, send one Explore subagent on the haiku model with a narrow question (the main flow's files and functions; in deep, one subagent per extra flow), never "map everything". quick never needs one.
• Write the DATA file once with one Write. Fix build or verify errors with Edit, never by rewriting the file. Don't read back the JSON or the built HTML.
• Don't syntax-check the page; the template is fixed and already tested. build.py and verify.py are the only checks.

Three depths

Every page is built at one depth. Pick it from the user's words; default to full. Set it as project.mode.

Depth changes how much you read and write, never the template. In quick, stop reading as soon as you can name the layers and the one flow: grep the flow files for function signatures and read only the lines around them (about 100 lines in all is usually enough); don't read the database or git history. In deep, check every note yourself in the code before keeping it (drop any a subagent can't back with a line), but leave line numbers in inside to verify.py instead of grepping each one.

Workflow

1. Find the project and the depth

The user usually types /explain. Whatever follows is the input, in any order: a depth word (above), a language word, a path (/explain ~/Projects/shop), a part to focus on (/explain the payment flow), or nothing (the current project at full). /explain سريع ~/Projects/shop and /explain deep payments both work. A focus doesn't change the depth; it makes the main flow follow that focus. If the working directory isn't a project and no path was given, ask which project; don't guess.

2. Map it in one call

python3 -I SKILL/scripts/scan.py <project-root>

From the output decide, within the depth's budget: the layers, the parts (layer nodes) that matter, the most common user action, whether there is a database worth a section, and whether git history is rich enough for a story. Then read only the central files: the entry point, the main state holder, controller or service, the data model, and the two or three files on the main flow's path.

3. Choose the analogy

Pick one analogy from the project's own world, so the reader already knows the roles: a scoreboard and umpire for a sports app, reception, doctor and medical file for a clinic, cashier and warehouse for a shop, a post office for chat, a restaurant for a generic backend. Map each role to one real class; mark the most central one key: true. 4–6 roles.

4. Write the DATA file

Read SKILL/references/data.md for the JSON shape, the rules for each field and each depth's sizes, then write the file in a scratch folder (not inside the user's project) in one go. Read SKILL/references/figures.md only if a figure would explain something the built-in sections can't (where things run, a safety or payment pipeline, a state machine); most pages need none.

5. Verify and build

python3 -I SKILL/scripts/verify.py <data.json> <project-root>
python3 -I SKILL/scripts/build.py <data.json> <out.html>

verify.py checks every cited path, every exercise line number and snippet, and every story commit against the repo, and prints only problems. Fix each one with a small Edit and rerun. build.py checks the structure (ids, links, sections) and writes the page. Put the HTML in the scratch folder unless the user wants it in the project (for example docs/شرح-المشروع.html, or docs/explained.html for an English page).

6. Deliver

If the Artifact tool is available, publish the HTML as an artifact (icon book) and give the link. Otherwise rebuild it with --standalone (a complete HTML document), open the file in the browser and give its absolute path. The page is one self-contained file. Remind the user that it shows their file names, folders and commit messages before they share it. Reply in the page's language: the depth, what the page covers, and anything you could not verify. After a quick or full page, mention in one line that a deeper one is available.

Writing the page

The page succeeds or fails on the writing. Write how a good teacher talks, not how a manual reads. In both languages:

• Short sentences, one idea per sentence. No padding: every sentence teaches something about this project.
• Say what a part does in the reader's terms before naming the technology.
• Code names, file names and packages stay exactly as in the code. Western digits (0–9) for numbers and line numbers.

English pages: plain, direct English, "you" for the reader. "Saves the score on the phone after every point" before "uses SharedPreferences". Explain a framework term in a few words on first use instead of assuming it ("a hook, a React function that keeps state").

Arabic pages:

• Clear Modern Standard Arabic.
• Say what a part does in the reader's terms before naming the technology: «يحفظ النتيجة في ذاكرة الهاتف بعد كل نقطة» before «يستخدم SharedPreferences».
• Code names, file names and packages stay in English exactly as in the code. On first use of a concept give both: «المستودع (Repository)».
• If a sentence sounds translated, rewrite it from scratch.

What to avoid

• Inventing parts, or describing what a framework usually does instead of what this project does.
• Listing every file; the folder tree covers the rest.
• An analogy from the wrong world (a restaurant for a booking system).
• Changing the template's layout. Consistency across projects is the point; put the effort into the content.