Przejdź do treści
Biblioteka skilli
Programowanie · Nauka i wyjaśnianie

explain

/explain

Tłumaczy działanie projektu programistycznego w formie interaktywnej strony z analogią, mapą warstw i przepływem jednego żądania.

Licencja
MIT
Ostatnia zmiana repozytorium
10.11.2026

Ocena i bezpieczeństwo

95/ 100Klasa: dobry
Format20 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
6
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 10.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Tłumaczy działanie projektu programistycznego w formie interaktywnej strony z analogią, mapą warstw i przepływem jednego żądania.

Wyzwalacze z opisu

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
Oryginalny opis (EN)

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

Jak działa

  1. Language
  2. Keep it cheap
  3. Three depths
  4. Workflow
  5. Writing the page
  6. What to avoid
Sekcje z nagłówków SKILL.md, w oryginale · 98 linii, 1 393 słów
Podgląd SKILL.md
---
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.
Pliki w paczce (6)
  • .gitignore 1 KB
  • DESIGN.md 18 KB
  • LICENSE 1 KB
  • PRODUCT.md 3 KB
  • README.md 24 KB
  • SKILL.md 9 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · 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

Migawka bazy z 13.11.2026 · wersja paczki 4bafb412106a (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100codebase-onboard
    Mapuje i wyjaśnia nieznany projekt JavaScript, TypeScript lub Python: architekturę, punkty wejścia, przepływ danych i miejsce zmiany.
  • 100code-slowmo
    Wyjaśnia kod na interaktywnej stronie HTML z klikalną mapą systemu, osią czasu komunikacji między częściami i wykonaniem prawdziwego kodu linia po linii z logiem i zmieniającymi się wartościami.
  • 100arch-tutor
    Czyta repozytorium i tłumaczy właścicielowi jego architekturę: mapę warstw, ścieżkę jednego żądania, zadania w tle i wdrożenie.
  • 100onboard-codebase
    Mapuje nieznane repozytorium na podstawie faktycznie przeczytanych plików: czym jest, punkty wejścia, uruchamianie, testy i ryzyka.
  • 100codebase-documenter
    Tworzy jeden plik docs/CODEBASE.md z architekturą, komponentami, przepływem danych i instrukcją uruchomienia, aby zrozumieć i opisać nieznany projekt.
  • 100codebase-documenter
    Tworzy jeden plik docs/CODEBASE.md z architekturą, komponentami, przepływem danych i instrukcją uruchomienia, aby zrozumieć i opisać nieznany projekt.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.