explain
/explain
Explain any software project in plain Arabic or English as an interactive explainer page (right-to-left for Arabic) with a real-world analogy, a clickable map of the project's layers, a step-by-step flow of one request, the screens or entry points, a glossary, a "where do I change what" table and starter exercises. Use whenever the user wants to understand, explain, document, teach or onboard someone to a codebase, for example "explain this project", "help me understand this repo", "how does this code work", "map out this codebase for me", "I inherited this project and don't get it", "onboard
- Author
- AmrSabbagh35 ↗
- Repository
- project-explainer ↗
- Licence
- MIT
- Last repository change
- 10.11.2026
Assessment and security
- Files in this package
- 37
- Scripts
- 4
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 10.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 4 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: examples/make-depths.py, scripts/build.py, scripts/scan.py, scripts/verify.py
What it does and when to use it
Explain any software project in plain Arabic or English as an interactive explainer page (right-to-left for Arabic) with a real-world analogy, a clickable map of the project's layers, a step-by-step flow of one request, the screens or entry points, a glossary, a "where do I change what" table and starter exercises. Use whenever the user wants to understand, explain, document, teach or onboard someone to a codebase, for example "explain this project", "help me understand this repo", "how does this code work", "map out this codebase for me", "I inherited this project and don't get it", "onboard
Triggers from the description
Original author description
Explain any software project in plain Arabic or English as an interactive explainer page (right-to-left for Arabic) with a real-world analogy, a clickable map of the project's layers, a step-by-step flow of one request, the screens or entry points, a glossary, a "where do I change what" table and starter exercises. Use whenever the user wants to understand, explain, document, teach or onboard someone to a codebase, for example "explain this project", "help me understand this repo", "how does this code work", "map out this codebase for me", "I inherited this project and don't get it", "onboard
How it works
- Language
- Keep it cheap
- Three depths
- Workflow
- Writing the page
- What to avoid
SKILL.md preview
---
name: explain
description: Explain any software project in plain Arabic or English as an interactive explainer page (right-to-left for Arabic) with a real-world analogy, a clickable map of the project's layers, a step-by-step flow of one request, the screens or entry points, a glossary, a "where do I change what" table and starter exercises. Use whenever the user wants to understand, explain, document, teach or onboard someone to a codebase, for example "explain this project", "help me understand this repo", "how does this code work", "map out this codebase for me", "I inherited this project and don't get it", "onboard the new devs", "اشرح لي هذا المشروع", "شرح كامل بالعربية", "كيف يعمل هذا الكود", "ارسم لي مكونات المشروع", "أريد أن أفهم مشروع استلمته", or a vibe-coded project they don't understand yet, even if they don't say "skill", "diagram" or "page". Three depths: quick (سريع), full (default) and deep (عميق) with extra flows, function-level detail and review notes.
license: MIT
---
# /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`.
| Mode | Words that pick it | Who it's for | What the page has | Rough cost |
|---|---|---|---|---|
| `quick` | سريع، مختصر، نظرة سريعة، quick, short, overview, tl;dr | "What is this?" in 5 minutes | the one-liner, 2–4 layers with 5–12 parts, one flow of 3–5 steps, 4–6 "where do I change" rows, optionally a 3-role analogy and 5 words | ~25k tokens |
| `full` | كامل، شرح، (nothing), full | learning the project, onboarding | everything below at the normal size: analogy, 12–22 parts, one flow, database, story, screens, glossary, change table, 3 exercises, tree | ~40–50k |
| `deep` | عميق، مفصل، تفصيلي، للمراجعة، deep, detailed, in depth, review | maintainers and reviewers who will change the code | full, plus: 16–32 parts, 2–3 flows (`moreFlows`), what is inside each central part (`inside`: key functions with line numbers), review notes (`notes`: gaps, risks, security, tech debt, performance), 4–5 exercises, and figures where they help | ~90–100k, plus Haiku helpers on big repos |
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
```bash
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
```bash
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.
Files in this package (37)
- .gitignore 1 KB
- DESIGN.md 18 KB
- LICENSE 1 KB
- PRODUCT.md 3 KB
- README.md 24 KB
- SKILL.md 9 KB
- assets/template.html 69 KB
- docs/.nojekyll 1 KB
- docs/cast.png 179 KB
- docs/depths.svg 4 KB
- docs/english.png 203 KB
- docs/flow.png 137 KB
- docs/how-it-works.svg 4 KB
- docs/index.html 7 KB
- docs/map.png 192 KB
- docs/notes.png 182 KB
- docs/themes.png 120 KB
- docs/demo/deep-en.html 98 KB
- docs/demo/deep.html 102 KB
- docs/demo/full-en.html 91 KB
- docs/demo/full.html 94 KB
- docs/demo/quick-en.html 74 KB
- docs/demo/quick.html 75 KB
- examples/deploy-en.svg 2 KB
- examples/deploy.svg 2 KB
- examples/make-depths.py 4 KB
- examples/sample-deep-en.json 21 KB
- examples/sample-deep.json 25 KB
- examples/sample-en.json 22 KB
- examples/sample-quick-en.json 7 KB
- examples/sample-quick.json 9 KB
- examples/sample.json 25 KB
- references/data.md 10 KB
- references/figures.md 4 KB
- scripts/build.py 13 KB
- scripts/scan.py 11 KB
- scripts/verify.py 7 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · AmrSabbagh35/project-explainer | 95 | MIT |
| crbnos/carbon | 100 | AGPL-3.0 |
| PerilloAI/flowtrace-plugin | 100 | Apache-2.0 |
| mickeyyaya/evolve-loop | 100 | Apache-2.0 |
| zenobi-us/dotfiles | 100 | MIT |
| imgly/agent-skills | 100 | MIT |
| marcel-bich/marcel-bich-claude-marketplace | 100 | MIT |
| nicodiansk/draw-it-out | 100 | MIT |
| ramboz/jig | 100 | MIT |
Database snapshot: 13.11.2026 · package version 0b85bcc5ea17 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100codebase-onboard
Quickly map and explain an unfamiliar JavaScript/TypeScript or Python codebase — architecture, entry points, data flow, how to run it, and where to make a given change. Use whenever the user opens a new project, asks "explain this repo", "gimana struktur project ini", "where is… - 100code-slowmo
Explains code with an interactive visual page instead of a wall of text. It builds one HTML file with a clickable map of the system, a step-by-step timeline of what each part tells the others, and a line-by-line run of the real code that shows changing values, a log and a mock… - 100arch-tutor
Read a project's repository and explain its architecture to its owner as a tutor would - a visual map (layers, the path of one request, background jobs, deploy) with a plain-language note on every framework, a knowledge-base page with a glossary, and an architecture review of up… - 100onboard-codebase
Map an unfamiliar repository from the files actually read (what it is, entry points, how to run and test it, conventions, risks) and propose lines for the project memory. Use it when starting in a project new to you, when asked to explain or map a codebase, or while its memory is empty. - 100codebase-documenter
Use this skill when the user wants to understand, document, or explain a codebase — even if they don't say "document" explicitly. Trigger on: "explain this codebase", "how does this project work", "create onboarding docs", "document the architecture", "I'm new to this repo",… - 100codebase-documenter
Use this skill when the user wants to understand, document, or explain a codebase — even if they don't say "document" explicitly. Trigger on: "explain this codebase", "how does this project work", "create onboarding docs", "document the architecture", "I'm new to this repo",…