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

code-walkthrough

/code-walkthrough

Wyjaśnia działanie funkcji lub miejsca w kodzie jako ponumerowany przewodnik z diagramem sekwencji Mermaid i krokami CodeTour w VS Code, z prawdziwymi przykładami żądań i błędów.

Licencja
MIT
Ostatnia zmiana repozytorium
24.10.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
1
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

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

Licencja

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

Co sprawdzić przed instalacją
  • 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/walkthrough.mjs

Co robi i kiedy

Wyjaśnia działanie funkcji lub miejsca w kodzie jako ponumerowany przewodnik z diagramem sekwencji Mermaid i krokami CodeTour w VS Code, z prawdziwymi przykładami żądań i błędów.

Wyzwalacze z opisu

code tour
Oryginalny opis (EN)

Explain how a feature or a code location works as a numbered walkthrough: a Mermaid sequence diagram (UI → HTTP → app → route → auth → controller → service → store → database) and a matching VS Code CodeTour whose steps highlight the exact code, with real request/response and error examples. Starts from a route, a feature, or a code location such as a SAST/Semgrep finding's sink, and finds the routes that reach it. Use when asked to walk through, trace, diagram, explain or "code tour" a flow, route, feature or finding.

Jak działa

  1. Inputs
  2. Files in this skill
  3. Ground rules
  4. Step 1: Find the flows
  5. Step 2: Read the whole path
  6. Step 3: Capture real examples
  7. Step 4: Write the spec
  8. Step 5: Build and check
  9. Step 6: Report
Sekcje z nagłówków SKILL.md, w oryginale · 123 linii, 1 116 słów
Podgląd SKILL.md
---
name: code-walkthrough
description: >-
  Explain how a feature or a code location works as a numbered walkthrough: a Mermaid sequence
  diagram (UI → HTTP → app → route → auth → controller → service → store → database) and a matching
  VS Code CodeTour whose steps highlight the exact code, with real request/response and error
  examples. Starts from a route, a feature, or a code location such as a SAST/Semgrep finding's sink,
  and finds the routes that reach it. Use when asked to walk through, trace, diagram, explain or
  "code tour" a flow, route, feature or finding.
---

# Code walkthrough: sequence diagram + CodeTour

Produce, for each flow, one spec file that a bundled script turns into a CodeTour and a Mermaid
diagram whose step numbers match one to one. The goal is **understanding**: a reader should follow
the diagram, open the tour, and see where each step lives in the code, what goes in and what comes out.

## Inputs

- **Target** (required): a route (`GET /orders`), a feature ("how users reset their password"), or a
  code location (`src/repositories/orderRepository.js:8`, a function name, or findings in a scanner
  report such as `semgrep.json`).
- **Output directory** (optional): defaults to `docs/flows/` for specs and pages, `.tours/` for tours.

If the target is ambiguous, ask once. Otherwise proceed.

## Files in this skill

- `${CLAUDE_PLUGIN_ROOT}/skills/code-walkthrough/references/flow-spec.md`: the spec format. **Read it before writing a spec.**
- `${CLAUDE_PLUGIN_ROOT}/skills/code-walkthrough/scripts/walkthrough.mjs`: builds and checks the outputs. Run it from the target repo root:
  `node ${CLAUDE_PLUGIN_ROOT}/skills/code-walkthrough/scripts/walkthrough.mjs build docs/flows` (or `check`).

## Ground rules

1. **Evidence only.** Every code step points at code you read, through a `pattern` that matches
   exactly once. Never guess a location.
2. **Never fabricate examples.** Requests, responses, status codes, error bodies and log lines are
   either captured from the running app in this session, or derived from the code and labelled
   `(derived from code, not run)`. Never present derived output as observed.
3. **Explain, don't judge.** Describe what the code does ("`sort` is not validated",
   "`tableName` is written into the SQL text"). Don't give exploitability verdicts or severities:
   that's a triage task, not a walkthrough.
4. **Local and harmless only.** If you run the app, run it locally, send only normal requests and
   the error cases the flow already handles (missing auth, wrong role, invalid input). No attack
   payloads. Stop anything you started when you're done.
5. **Don't touch application code.** Write only the spec files and the generated outputs.

## Step 1: Find the flows

- **From a code location:** find every caller, up to the entry points: search for the function
  name, then its callers' names, until you reach route declarations, message consumers, jobs or CLI
  commands. Each entry point that reaches the location is **one flow**. List them with the call
  chain as evidence (`route → controller.fn → service.fn → repo.fn`), and say explicitly if a
  location has no caller or several.
- **From a route or feature:** find the route declaration and follow it forward.

## Step 2: Read the whole path

Read every file on the path completely, not just the lines around the call: app setup (middleware
order, body parsers, error handler), router, every middleware in the chain, controller, service,
data access, config the flow reads, and the view/template if one renders the result.
Note where each value comes from and every time a value is **renamed** between layers.

## Step 3: Capture real examples

If the app can run locally (README, `package.json` scripts, docker-compose), start it and send
requests for the success case and for **every error branch** the flow has: no credentials, invalid
credentials, wrong role, invalid input, not found, and a server error if a normal input causes one.
Record the exact status line and body, plus any relevant server log line. If it can't run, derive
the examples from the code and label them as derived.

## Step 4: Write the spec

One `docs/flows/<id>.flow.json` per flow, in the format of `${CLAUDE_PLUGIN_ROOT}/skills/code-walkthrough/references/flow-spec.md`.

**Steps**
- Step 1 is the client's HTTP request (text only): a sample request, then a table of every possible
  response (case, status, body).
- Then one step per meaningful hop, in execution order: app setup / router mounting, route
  declaration (with its handler chain), each middleware check, each controller action (read input,
  validate, call the next layer), each service decision, the data-access call, the external system
  (database, HTTP API; text only), and the response(s), including the error handler.
- A step is worth its own number if it: moves the request to another file or layer, reads or
  transforms an input, enforces a control (`kind: control`), renames a value, or is the location
  being asked about (`kind: sink`). Merge trivial pass-throughs into the next step.
- Include every security-relevant location on the path, even the ones that look fine: that's
  what the reader needs to compare.
- **Title:** `Layer: action`, 2–6 words. **Pattern:** capture exactly the part the description
  talks about (the argument, the condition, the interpolation), not the whole line.
- **Description**, in this order: `**What happens:**` (1–3 sentences) · example (request,
  value, SQL, response or error, in a fenced block) · `**Security:**` (optional, factual) ·
  `**Next →** <the call that invokes the next step> (step N)`.
- `note`: 1–3 short lines for the diagram: the key code, a concrete value, or "x is not checked".

**Lanes**
- Same order in every flow of a run, left to right as the request travels:
  Client · Framework/routing (`Express`) · Auth · Controller · Config (only if read) · Service ·
  Store (data access) · external systems (`Postgres`, an API). Drop lanes a flow doesn't use; don't
  reorder them.
- Several files in one lane is expected (app setup + router, auth middleware + user lookup).
  The script draws them as stacked file boxes in one column; add a self-arrow for each hand-off
  between files in the same lane.

**Diagram**
- Wrap consecutive events in **phases**: Routing · Authentication (· Authorization) · Input handling
  · Data access · Response. Add Business logic, External call or Rendering only if the flow has them.
- Every call is a solid arrow labelled with the actual call (`requireAuth(req, res, next)`,
  `find(user.id, status, orderBy)`); every return and response is dashed.
- Every error exit is a `break` with the real response. Use `alt` only for a fork where both
  branches continue (rows vs. database error).
- Show values being renamed across layers with a note (`sort is renamed orderColumn`).

## Step 5: Build and check

```
node ${CLAUDE_PLUGIN_ROOT}/skills/code-walkthrough/scripts/walkthrough.mjs build docs/flows
node ${CLAUDE_PLUGIN_ROOT}/skills/code-walkthrough/scripts/walkthrough.mjs check docs/flows
```

Fix every reported problem (pattern matched 0 or 2+ times, unknown lane, step missing from the
diagram) and rebuild until `check` passes. Then open each generated `docs/flows/<id>.md` and read the
step table: every code location must be the line the step talks about.

## Step 6: Report

Tell the user:
- the flows found, and the evidence for how the target is reached (call chain per entry point);
- the files written (`docs/flows/*.flow.json`, `docs/flows/*.md`, `.tours/*.tour`);
- which examples were captured from the running app and which were derived;
- how to follow along: install the CodeTour extension (`vsls-contrib.codetour`), open the tour,
  step N = diagram step N; after code changes, re-run `build` (the command above) to move the highlights with the code,
  or `check` in CI.
Pliki w paczce (3)
  • SKILL.md 8 KB
  • references/flow-spec.md 7 KB
  • scripts/walkthrough.mjs 9 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · mohamed-osama-aboelkheir/appsec-untangled-resources100MIT
dkarter/dotfiles100MIT
testdouble/han100MIT
312362115/claude100MIT
motlin/claude-code-plugins95Apache-2.0

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

  • 100code-tour
    Tworzy przewodnik po kodzie jako plik .tour JSON dla rozszerzenia CodeTour w VS Code, z zapasową wersją w Markdown, dla wdrożenia, architektury i przeglądu pull requestów.
  • 100code-tour
    Tworzy pliki CodeTour z krokami dla wybranego odbiorcy, z kotwicami do plików i linii, do wdrożeń i przeglądów.
  • 100code-tour
    Tworzy pliki CodeTour .tour: krokowe przewodniki dopasowane do odbiorcy, z odnośnikami do prawdziwych plików i linii, dla wdrożenia, architektury, pull requestów i analizy przyczyn.
  • 100source-to-sink
    Śledzi przepływ danych między wejściami a wrażliwymi miejscami w kodzie i prezentuje go jako diagram z kartami kodu.
  • 100code-tour
    Tworzy pliki CodeTour .tour: dopasowane do osoby, krokowe przewodniki z odnośnikami do prawdziwych plików i linii, na przykład wprowadzające, architektoniczne i dla pull requestów.
  • 100explain-code-flow
    Wyjaśnia przepływ działania funkcji w czasie wykonania, transformacje danych i kontrakty wejścia i wyjścia jako wizualną narrację z diagramami Mermaid.

Uwagi i zgłoszenia

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