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

how

/how

Wyjaśnia, jak działa część bazy kodu, przechodzi przez kod przed zmianą i wskazuje, gdzie powinien leżeć nowy kod.

Repozytorium
skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 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
3
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.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

Wyjaśnia, jak działa część bazy kodu, przechodzi przez kod przed zmianą i wskazuje, gdzie powinien leżeć nowy kod.

Wyzwalacze z opisu

where should this livewhich module owns thisis this the right layer
Oryginalny opis (EN)

Explain how a part of the codebase works, walk the code before a change, and answer placement questions such as "where should this live", "which module owns this" or "is this the right layer". Reads the wiki, decision records and glossaries first, then the code, and sends read-only subagents for large questions. Use when the user asks how something works, wants a walkthrough before changing code, or asks where code belongs.

Jak działa

  1. Steps
  2. Do
  3. Don't
Sekcje z nagłówków SKILL.md, w oryginale · 146 linii, 925 słów
Podgląd SKILL.md
---
name: how
description: Explain how a part of the codebase works, walk the code before a change, and answer placement questions such as "where should this live", "which module owns this" or "is this the right layer". Reads the wiki, decision records and glossaries first, then the code, and sends read-only subagents for large questions. Use when the user asks how something works, wants a walkthrough before changing code, or asks where code belongs.
disable-model-invocation: true
---

# How

An engineer who asks "how does checkout work?" wants a map, not a tour of
every line. Half of that map is often in the docs already. A decision record
says why a seam sits where it does, and the glossary names each module.

This skill reads those docs first, then the code. A senior engineer new to the
area can start work from its explanation. It builds a mental model, not
annotated source.

Every subagent here only reads. Hand-offs go through files in your scratchpad,
called `$WORK` below, so file dumps stay out of your context.

## Steps

### 1. Frame the question

Restate the question in one sentence. When the scope is unclear, state your
reading and go on. The user can redirect.

Name the kind:

- **Flow.** How does X work, or what happens when Y.
- **Walkthrough.** The code a planned change will touch, before the change.
- **Placement.** Where new code belongs, which module owns a thing, or whether
  a layer is right.

Done when the restated question and its kind are written down.

### 2. Read the docs first

Find what the bundle already says. Use the paths and words from the question:

```sh
node scripts/find-docs.ts --links-to <path>
node scripts/find-docs.ts --search "<words>"
node scripts/find-docs.ts --type Decision --status accepted --search "<words>"
```

- `find-docs.ts` exits 1 when nothing matches. That is a result, not an error.
- Read every page it prints in full.
- For a placement question, also search the decisions by each module involved:
  `--type Decision --links-to <module path>`.

Then look up each term of the question in the glossaries. Their paths are in
`agents.config.json` under `docs.glossaries`, relative to `docs.root`. A
technical entry's **Code** line names the directory that holds the term.

Write `$WORK/docs.md`: each page and decision record you read, one line each
on what it says about the question, and the glossary entries you used.

Done when `docs.md` exists and lists each source found, or names the searches
that found nothing.

### 3. Pick the path

- **Simple.** One module, a small utility, or a narrow question such as "how
  does function X work". Go to step 5 without explorers.
- **Complex.** A subsystem across several files or services, a feature that
  cuts across modules, or a full architectural overview. Go to step 4.

When in doubt, take the simple path. Most placement questions are simple.

Done when you have named the path.

### 4. Explore, complex path only

Split the question into two to four angles. Each angle is a distinct slice of
the subsystem, such as the entry point, the data model, or where outside data
enters.

Start one read-only subagent per angle, all in one message. Use the CLI's
subagent tool, such as Agent, on a fast model, such as Sonnet. Each prompt
holds:

- the path to [`explorer.md`](explorer.md), its brief,
- the question and its angle,
- the path to `$WORK/docs.md`,
- its output file, `$WORK/explorer-<n>.md`.

When subagents cannot be started, trace each angle yourself from its brief.

Done when every explorer has returned and each output file exists.

### 5. Explain

Start one read-only subagent on the strongest model, such as Opus. Its prompt
holds:

- the path to [`explainer.md`](explainer.md), its brief,
- the question and its kind,
- the path to `$WORK/docs.md`,
- the paths of the explorer files, when step 4 ran,
- its output file, `$WORK/explanation.md`.

When subagents cannot be started, follow the explainer brief yourself.

Done when `explanation.md` exists and has the sections the brief requires for
the question's kind.

### 6. Present

Give the user the explanation. Edit it lightly for clarity or for context
from this conversation. Do not rewrite it.

Then report what the docs need, worst first:

```
🔴 <page or record>: <where it disagrees with the code, and which is right>
🟡 <term or page>: <a term the glossaries lack, or a gap a page should fill>
🟢 docs: <the pages that matched the code>
```

- When a page disagrees with the code, offer to fix it with `h2xd:docs-wiki`.
- When a term is missing, offer to add it with `h2xd:docs-glossary`.
- When the answer drew on several pages and will be asked again, offer to file
  it as a page with `h2xd:docs-wiki`.
- When a placement answer settles a seam that is hard to reverse, and no
  record decides it, offer `h2xd:docs-adr`.

When another skill started you with an output file, write the explanation and
the report there. Leave the offers to that skill.

Done when the user or the caller's output file has the explanation and report.

## Do

- Read the docs bundle before the code. A decision record often answers "why
  here" in one paragraph.
- Name modules and concepts by their glossary heading.
- Cite every claim about the code with a file path and a function name.
- Answer a placement question with one recommendation and the rule behind it.
- Say which parts the explorers could not trace.

## Don't

- Don't change code or docs in this skill. Report the gap and offer the skill
  that fixes it.
- Don't trust a page over the code. Check it, and report the disagreement.
- Don't start explorers for a narrow question. Take the simple path.
- Don't paste large code blocks. Name the file and function, and quote a
  snippet only when the point depends on it.
- Don't invent a placement rule. Cite a decision record, a glossary **Code**
  line, or the pattern of the neighboring code, and say which.
Pliki w paczce (3)
  • SKILL.md 6 KB
  • explainer.md 3 KB
  • explorer.md 2 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · h2xd/skills100MIT
sma1lboy/rove100MIT
flora131/atomic100MIT
pantheon-org/tekhne100MIT
jstarfilms/vibecode-protocol-suite100ISC
scino/fstack100MIT
irg1008/cstack100MIT
shrimpwtf/oh-my-pstack100MIT
caezium/skills100MIT

Migawka bazy z 13.11.2026 · wersja paczki e242392693b9 (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

  • 80workflow-how
    Wyjaśnia, jak działa podsystem, jego przepływ w czasie działania i gdzie powinien leżeć kod, dla nowych w projekcie.
  • 100comms-how
    Wyjaśnia, jak działa podsystem Flowstate: architekturę, przepływ w czasie wykonania i miejsce na nowy kod.
  • 85swe-110-explain-a-codebase
    Czyta nieznany kod i wyjaśnia go człowiekowi bez zmian: jak działa projekt, gdzie coś się dzieje i jak go uruchomić.
  • 100codebase-structure
    Wskazuje, gdzie w projekcie powinien leżeć kod: warstwy architektury, nazwy plików i folderów oraz granice pakietów.
  • 90walk-with-me
    Przeprowadza użytkownika przez kod krok po kroku jako code walk zamiast raportu, na przykład przy prośbie o wyjaśnienie bazy kodu.
  • 100wiki-qa
    Odpowiada na pytania o repozytorium wyłącznie na podstawie dowodów z kodu źródłowego, na przykład jak działa funkcja lub gdzie zdefiniowano komponent.

Uwagi i zgłoszenia

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