Skip to content
Skills Library
Programming · Learning & explanation

how

/how

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.

Author
h2xd ↗
Repository
skills ↗
Licence
MIT
Last repository change
12.11.2026

Assessment and security

100/ 100Class: good
Format25 / 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
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

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

What it does and when to use it

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.

Triggers from the description

where should this livewhich module owns thisis this the right layer
Original author 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.

How it works

  1. Steps
  2. Do
  3. Don't
Original SKILL.md headings · 146 lines, 925 words
SKILL.md preview
---
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.
Files in this package (3)
  • SKILL.md 6 KB
  • explainer.md 3 KB
  • explorer.md 2 KB

Versions

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

Database snapshot: 13.11.2026 · package version e242392693b9 (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

  • 80workflow-how
    Use for \"how does X work\", code walkthroughs before changing something, and placement / ownership / layering questions (\"where should this live\", \"which package owns this\", \"is this the right layer\"). Explains subsystem architecture, runtime flow, onboarding mental…
  • 100comms-how
    Explain how a subsystem works, its architecture, runtime flow, and where new code belongs. Use for "how does X work", walkthroughs before changing something, and placement or ownership questions like "where should this live" or "which package owns this". Use comms-why for motivation.
  • 85swe-110-explain-a-codebase
    Read an unfamiliar codebase and explain it to a person without changing anything. Use when asked how a project works, where something happens, or how to run it, and before any change to code you haven't read.
  • 100codebase-structure
    Where code belongs in a codebase — architectural layers, file and folder naming, imports and barrels, package boundaries. Use when adding, moving, or renaming files; building a page, screen, or route; scaffolding a feature or package; or reviewing structure, even if conventions aren't mentioned.
  • 90walk-with-me
    Use when the user wants to be walked through code, not handed a report: "walk through this", "guided code walk", or "explain this codebase". Not for tasks that require source or remote-system changes.
  • 100wiki-qa
    Answer repository questions grounded entirely in source code evidence. Use when user asks a question about the codebase, user wants to understand a specific file, function, or component, or user asks \"how does X work\" or \"where is Y defined\".

Feedback and reports

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