Skip to content
Skills Library
Programming · Writing

build-study-guide

/build-study-guide

Review a codebase and generate layered, evidence-cited onboarding docs (overview, per-layer, gotchas, how-to-build, how-to-run-and-debug) under docs/onboarding/. Use when the user wants to onboard to or document an unfamiliar repo, or runs /tutor:build-study-guide.

Repository
tutor ↗
Licence
Apache-2.0
Last repository change
10.06.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
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Review a codebase and generate layered, evidence-cited onboarding docs (overview, per-layer, gotchas, how-to-build, how-to-run-and-debug) under docs/onboarding/. Use when the user wants to onboard to or document an unfamiliar repo, or runs /tutor:build-study-guide.

Arguments

/build-study-guide [path] [--perspective structure|data-flow|security|use-cases|gotchas|comprehensive] [--axis service|component|feature|la
Original author description

Review a codebase and generate layered, evidence-cited onboarding docs (overview, per-layer, gotchas, how-to-build, how-to-run-and-debug) under docs/onboarding/. Use when the user wants to onboard to or document an unfamiliar repo, or runs /tutor:build-study-guide.

How it works

  1. Inputs
  2. Procedure
  3. Refresh (--refresh)
  4. Drive-to-code rule
  5. See also
Original SKILL.md headings · 129 lines, 1,106 words
SKILL.md preview
---
name: build-study-guide
description: Review a codebase and generate layered, evidence-cited onboarding docs (overview, per-layer, gotchas, how-to-build, how-to-run-and-debug) under docs/onboarding/. Use when the user wants to onboard to or document an unfamiliar repo, or runs /tutor:build-study-guide.
user-invocable: true
disable-model-invocation: true
argument-hint: "[path] [--perspective structure|data-flow|security|use-cases|gotchas|comprehensive] [--axis service|component|feature|layer] [--refresh]"
---

# /tutor:build-study-guide

Produce living, evidence-based onboarding docs for a repo by reading the actual code, citing every claim, and writing a structured doc set under `docs/onboarding/`.

## Inputs

| Argument | Default | Notes |
|----------|---------|-------|
| `path` | Current working directory | Repo root to analyze. |
| `--perspective` | `comprehensive` | Lens to emphasize: `structure`, `data-flow`, `security`, `use-cases`, `gotchas`, or `comprehensive`. |
| `--axis` | Auto-detected | Override the decomposition axis: `service`, `component`, `feature`, or `layer`. Skips detection; still confirm the layer list with the user. |
| `--refresh` | Off | Regenerate stale docs rather than doing a full rebuild. See **Refresh** below. |

## Procedure

### 1. Check for existing docs

Resolve the target repo root (from `path`, or cwd) and its `docs/onboarding/` directory.

If `docs/onboarding/index.md` already exists **and `--refresh` was NOT passed**:

- Run the **Freshness** procedure defined in `${CLAUDE_PLUGIN_ROOT}/references/conventions.md`.
- Tell the user that docs already exist, show the freshness assessment, and offer `/tutor:study` instead of rebuilding.
- Only continue a full build if the user explicitly confirms they want to overwrite.

### 2. Detect the axis

Inspect build files (e.g. `build.gradle`, `package.json`, `Makefile`, `pyproject.toml`), module/package layout, and directory conventions to propose a decomposition axis (`service | component | feature | layer`) and a concrete, ordered layer breakdown.

Present the proposed axis and layer list to the user via AskUserQuestion and ask them to confirm or edit. If `--axis` was given, skip detection and go straight to confirming the layer list.

### 3. Pick the perspective

Unless `--perspective` was given, ask the user which lens to emphasize via AskUserQuestion:

- `structure` — component relationships and module boundaries
- `data-flow` — how data moves end-to-end
- `security` — trust boundaries, auth, secrets handling
- `use-cases` — key user journeys through the code
- `gotchas` — cross-cutting pitfalls and surprises
- `comprehensive` — all of the above (default)

### 4. Analyze thoroughly, citing as you go

For each confirmed layer, read the actual source files and capture:

- What the layer does and its responsibility boundary.
- How data enters, is transformed, and exits.
- Key use cases or request paths it serves.
- Gotchas: surprising behaviors, performance traps, ordering dependencies, misnamed abstractions.

For breadth, you MAY dispatch one subagent per layer to do mechanical reading; each subagent must return a cited topic list (file:line references, not prose summaries). **Every claim must carry a `file:line` citation** using the format defined in `${CLAUDE_PLUGIN_ROOT}/references/conventions.md`. If you cannot cite a claim, keep investigating until you can — or drop it.

### 5. Write the docs

Write the complete doc set exactly per the directory layout, `index.md` front-matter format, layer-doc structure, `## Topics` section format, difficulty tags, and citation format defined in `${CLAUDE_PLUGIN_ROOT}/references/conventions.md`. Do not invent alternate formats.

Files to produce:

- `docs/onboarding/index.md` — front-matter with the CURRENT `git rev-parse HEAD` (short hash), branch, dirty state (`true`/`false`), today's date, the confirmed axis, and the chosen perspectives; followed by the linked layer table.
- `docs/onboarding/00-overview.md` — architecture overview, end-to-end data-flow, and the full layer map with brief per-layer descriptions.
- `docs/onboarding/NN-<layer>.md` — one file per layer (zero-padded order: 01, 02, …), each with a free-form overview section followed by a `## Topics` section with ≥1 difficulty-tagged topic and ≥1 citation per topic.
- `docs/onboarding/gotchas.md` — cross-cutting pitfalls that span multiple layers or don't belong in a single layer doc.
- `docs/onboarding/how-to-build.md` — derived from README, build files, and CI configs. Every build step must be cited to the file where it appears.
- `docs/onboarding/how-to-run-and-debug.md` — derived from README, docker-compose, run configs, and CI. Cite each instruction to its source file.

#### Diagram generation

After drafting the overview prose and layer docs, decide whether to add diagrams, following
the diagram spec in `${CLAUDE_PLUGIN_ROOT}/references/conventions.md`.

**`00-overview.md`** — always include a system-level ASCII diagram in the prose body
(after the architecture summary, before any layer map table). Show each major component
and the primary data-flow edges between them. Use the drawing conventions in
`${CLAUDE_PLUGIN_ROOT}/references/conventions.md`.

**Layer docs (`NN-<layer>.md`)** — add a `## Diagram` section only when ALL three hold:

1. The active `--perspective` is `data-flow`, `security`, or `comprehensive`.
2. The layer has meaningful spatial structure: a pipeline (data enters, is transformed,
   exits through a clear sequence of steps) OR a trust/security boundary that is not
   obvious from the topic names alone.
3. The resulting diagram fits ≤ 12 labelled components. If not, omit it and use prose.

Place the `## Diagram` section between the overview prose and `## Topics`. For security
boundaries use a double-line box (`╔═ zone ═╗`) with untrusted callers shown outside
pointing in. Use a plain fenced code block (no language tag) — never `mermaid`.

Do **not** add diagrams to `gotchas.md`, `how-to-build.md`, or
`how-to-run-and-debug.md`.

For repos with no git history, still write the `gitHash`/`gitBranch`/`gitDirty` keys (the lint requires them) using placeholders — `gitHash: none`, `gitBranch: none`, `gitDirty: false` — and note in the overview that the repo is not under git. The Freshness procedure in `${CLAUDE_PLUGIN_ROOT}/references/conventions.md` already handles the non-git case.

### 6. Self-check

Run the bundled lint script and fix every reported problem before finishing:

```
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/lint_onboarding.py" <repo-root>
```

The script exits 0 when all conventions hold and every citation resolves to an existing file and line range; it exits 1 and prints each violation. Do not skip this step or report completion before the script exits 0.

### 7. Report

Tell the user:

- Which files were written and how many topics were captured per layer.
- The git hash the docs are pinned to.
- Any layers where coverage felt thin (citations were hard to find).
- Suggest `/tutor:study` to start learning from the generated docs.

## Refresh (--refresh)

1. Run the **Freshness** procedure from `${CLAUDE_PLUGIN_ROOT}/references/conventions.md` to determine which areas changed since `gitHash`.
2. Re-read and regenerate only the layer docs whose source areas changed (based on `git diff --name-only <gitHash>..HEAD`). Leave layer docs for unchanged areas and `.tutor/progress.md` untouched.
3. Rewrite `index.md`'s `gitHash`, `gitBranch`, `gitDirty`, and `generatedAt` to reflect the current state.
4. Re-run the lint script (step 6 above) over the full doc set before finishing.

## Drive-to-code rule

No uncited claims. A topic with zero citations is a bug. If you cannot point to a `file:line`, keep investigating until you can — or drop the claim entirely. This rule applies to every file in the doc set, including overview prose and the how-to docs. See `${CLAUDE_PLUGIN_ROOT}/references/conventions.md` for the exact citation format and regex.

## See also

- `${CLAUDE_PLUGIN_ROOT}/references/conventions.md` — authoritative formats for `index.md` front-matter, layer docs, `## Topics` structure, difficulty tags, citation syntax, `.tutor/progress.md`, the Freshness procedure, and the lint script.
- `${CLAUDE_PLUGIN_ROOT}/references/sample-repo/docs/onboarding/` — a worked example of the full target output.

Versions

The database has no other skills named build-study-guide.

Database snapshot: 13.11.2026 · package version 2835b67213a5 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100onboarding
    Generate or regenerate ONBOARDING.md to help new contributors understand a codebase. Use when the user asks to 'create onboarding docs', 'generate ONBOARDING.md', 'document this project for new developers', 'write onboarding documentation', 'vonboard', 'vonboarding', 'prepare…
  • 100onboarding
    Generate or regenerate ONBOARDING.md to help new contributors understand a codebase. Use when the user asks to 'create onboarding docs', 'generate ONBOARDING.md', 'document this project for new developers', 'write onboarding documentation', 'vonboard', 'vonboarding', 'prepare…
  • 100onboarding
    Generate or regenerate ONBOARDING.md to help new contributors understand a codebase. Use when the user asks to 'create onboarding docs', 'generate ONBOARDING.md', 'document this project for new developers', 'write onboarding documentation', 'vonboard', 'vonboarding', 'prepare…
  • 100onboard
    Instant Project Onboarding — generate a complete onboarding guide for any project. Use when user wants to onboard a new developer, understand a new codebase, or generate project documentation.
  • 90codebase-onboarding
    Use when joining a project or receiving a task in an unfamiliar codebase. Build a navigable map of an unfamiliar repository before proposing edits. Do not use when the task is unrelated to existing project code.
  • 90study
    Interactive, guided code walk through generated onboarding docs — one layer at a time or by a route you choose (e.g. start at the database, follow a request). Three study modes — guided (drive-to-code, default), lecture (dense, optional questions), reference (dense, no…

Feedback and reports

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