Skip to content
Skills Library
Programming · Learning & explanation

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

Licence
MIT
Last repository change
10.11.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
37
Scripts
4
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

where do I change whatexplain this projecthelp me understand this repohow does this code workmap out this codebase for meI inherited this project and don
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

  1. Language
  2. Keep it cheap
  3. Three depths
  4. Workflow
  5. Writing the page
  6. What to avoid
Original SKILL.md headings · 98 lines, 1,393 words
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

RepositoryScoreLicence
This page · AmrSabbagh35/project-explainer95MIT
crbnos/carbon100AGPL-3.0
PerilloAI/flowtrace-plugin100Apache-2.0
mickeyyaya/evolve-loop100Apache-2.0
zenobi-us/dotfiles100MIT
imgly/agent-skills100MIT
marcel-bich/marcel-bich-claude-marketplace100MIT
nicodiansk/draw-it-out100MIT
ramboz/jig100MIT

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",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.