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

code-tour

/code-tour

Tworzy pliki CodeTour .tour z krokowymi przewodnikami po kodzie, zakotwiczonymi w prawdziwych plikach i liniach, dla wdrożenia, architektury, pull requestów i analizy przyczyn.

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

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

Tworzy pliki CodeTour .tour z krokowymi przewodnikami po kodzie, zakotwiczonymi w prawdziwych plikach i liniach, dla wdrożenia, architektury, pull requestów i analizy przyczyn.

Wyzwalacze z opisu

explain how this works
Oryginalny opis (EN)

Create CodeTour `.tour` files — persona-targeted, step-by-step walkthroughs with real file and line anchors. Use for onboarding tours, architecture walkthroughs, PR tours, RCA tours, and structured "explain how this works" requests.

Jak działa

  1. When to Use
  2. When NOT to Use
  3. Workflow
  4. Step Types
  5. Writing Rule: SMIG
  6. Narrative Shape
  7. Example
  8. Anti-Patterns
  9. Best Practices
  10. Related Skills
Sekcje z nagłówków SKILL.md, w oryginale · 232 linii, 1 054 słów
Podgląd SKILL.md
---
name: code-tour
description: Create CodeTour `.tour` files — persona-targeted, step-by-step walkthroughs with real file and line anchors. Use for onboarding tours, architecture walkthroughs, PR tours, RCA tours, and structured "explain how this works" requests.
origin: ecc
---

# Code Tour

Create **CodeTour** `.tour` files for codebase walkthroughs that open directly to real files and line ranges. Tours live in `.tours/` and are meant for the CodeTour format, not ad hoc Markdown notes.

A good tour is a narrative for a specific reader:
- what they are looking at
- why it matters
- what path they should follow next

Only create `.tour` JSON files. Do not modify source code as part of this skill.

## When to Use

Use this skill when:
- the user asks for a code tour, onboarding tour, architecture walkthrough, or PR tour
- the user says "explain how X works" and wants a reusable guided artifact
- the user wants a ramp-up path for a new engineer or reviewer
- the task is better served by a guided sequence than a flat summary

Examples:
- onboarding a new maintainer
- architecture tour for one service or package
- PR-review walk-through anchored to changed files
- RCA tour showing the failure path
- security review tour of trust boundaries and key checks

## When NOT to Use

| Instead of code-tour | Use |
| --- | --- |
| A one-off explanation in chat is enough | answer directly |
| The user wants prose docs, not a `.tour` artifact | `documentation-lookup` or repo docs editing |
| The task is implementation or refactoring | do the implementation work |
| The task is broad codebase onboarding without a tour artifact | `codebase-onboarding` |

## Workflow

### 1. Discover

Explore the repo before writing anything:
- README and package/app entry points
- folder structure
- relevant config files
- the changed files if the tour is PR-focused

Do not start writing steps before you understand the shape of the code.

### 2. Infer the reader

Decide the persona and depth from the request.

| Request shape | Persona | Suggested depth |
| --- | --- | --- |
| "onboarding", "new joiner" | `new-joiner` | 9-13 steps |
| "quick tour", "vibe check" | `vibecoder` | 5-8 steps |
| "architecture" | `architect` | 14-18 steps |
| "tour this PR" | `pr-reviewer` | 7-11 steps |
| "why did this break" | `rca-investigator` | 7-11 steps |
| "security review" | `security-reviewer` | 7-11 steps |
| "explain how this feature works" | `feature-explainer` | 7-11 steps |
| "debug this path" | `bug-fixer` | 7-11 steps |

### 3. Read and verify anchors

Every file path and line anchor must be real:
- confirm the file exists
- confirm the line numbers are in range
- if using a selection, verify the exact block
- if the file is volatile, prefer a pattern-based anchor

Never guess line numbers.

### 4. Write the `.tour`

Write to:

```text
.tours/<persona>-<focus>.tour
```

Keep the path deterministic and readable.

### 5. Validate

Before finishing:
- every referenced path exists
- every line or selection is valid
- the first step is anchored to a real file or directory
- the tour tells a coherent story rather than listing files

## Step Types

### Content

Use sparingly, usually only for a closing step:

```json
{ "title": "Next Steps", "description": "You can now trace the request path end to end." }
```

Do not make the first step content-only.

### Directory

Use to orient the reader to a module:

```json
{ "directory": "src/services", "title": "Service Layer", "description": "The core orchestration logic lives here." }
```

### File + line

This is the default step type:

```json
{ "file": "src/auth/middleware.ts", "line": 42, "title": "Auth Gate", "description": "Every protected request passes here first." }
```

### Selection

Use when one code block matters more than the whole file:

```json
{
  "file": "src/core/pipeline.ts",
  "selection": {
    "start": { "line": 15, "character": 0 },
    "end": { "line": 34, "character": 0 }
  },
  "title": "Request Pipeline",
  "description": "This block wires validation, auth, and downstream execution."
}
```

### Pattern

Use when exact lines may drift:

```json
{ "file": "src/app.ts", "pattern": "export default class App", "title": "Application Entry" }
```

### URI

Use for PRs, issues, or docs when helpful:

```json
{ "uri": "https://github.com/org/repo/pull/456", "title": "The PR" }
```

## Writing Rule: SMIG

Each description should answer:
- **Situation**: what the reader is looking at
- **Mechanism**: how it works
- **Implication**: why it matters for this persona
- **Gotcha**: what a smart reader might miss

Keep descriptions compact, specific, and grounded in the actual code.

## Narrative Shape

Use this arc unless the task clearly needs something different:
1. orientation
2. module map
3. core execution path
4. edge case or gotcha
5. closing / next move

The tour should feel like a path, not an inventory.

## Example

```json
{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "API Service Tour",
  "description": "Walkthrough of the request path for the payments service.",
  "ref": "main",
  "steps": [
    {
      "directory": "src",
      "title": "Source Root",
      "description": "All runtime code for the service starts here."
    },
    {
      "file": "src/server.ts",
      "line": 12,
      "title": "Entry Point",
      "description": "The server boots here and wires middleware before any route is reached."
    },
    {
      "file": "src/routes/payments.ts",
      "line": 8,
      "title": "Payment Routes",
      "description": "Every payments request enters through this router before hitting service logic."
    },
    {
      "title": "Next Steps",
      "description": "You can now follow any payment request end to end with the main anchors in place."
    }
  ]
}
```

## Anti-Patterns

| Anti-pattern | Fix |
| --- | --- |
| Flat file listing | Tell a story with dependency between steps |
| Generic descriptions | Name the concrete code path or pattern |
| Guessed anchors | Verify every file and line first |
| Too many steps for a quick tour | Cut aggressively |
| First step is content-only | Anchor the first step to a real file or directory |
| Persona mismatch | Write for the actual reader, not a generic engineer |

## Best Practices

- keep step count proportional to repo size and persona depth
- use directory steps for orientation, file steps for substance
- for PR tours, cover changed files first
- for monorepos, scope to the relevant packages instead of touring everything
- close with what the reader can now do, not a recap

## Related Skills

- `codebase-onboarding`
- `coding-standards`
- `council`
- official upstream format: `microsoft/codetour`

Wersje

RepozytoriumWynikLicencja
Ta strona · mturac/everything-openai-codex100MIT
github/awesome-copilot100MIT
drvoss/everything-copilot-cli100MIT
borghei/Claude-Skills100MIT
alirezarezvani/claude-skills100MIT
SHRIJANAGAIN/Nemo-Cli100Apache-2.0
karurosux/code-tours.nvim100MIT
richardgill/nix100MIT
tmj-90/gaffer100Apache-2.0

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

  • 100create-code-tours
    Tworzy wycieczki po kodzie w plikach .tour dla nowych osób: opisuje domeny, zmiany w Gicie przez przyczyny i skutki oraz logikę biznesową krok po kroku.
  • 100doc-architect
    Generuje i naprawia warstwowe wytyczne AGENTS.md, aktualizuje dokumentację projektu, pliki CLAUDE.md i nagłówki skilli, pisze przewodniki CodeTour i poprawia lint Markdown bez zmiany znaczenia.
  • 1003d-virtual-tour
    Buduje prowadzone i interaktywne wirtualne wycieczki po środowisku 3D: ścieżki kamery, nawigację po pokojach i planie, tryb orbity i stopniowe ładowanie w Three.js.
  • 100add-product-tour
    Dodaje do aplikacji React lub Next.js tour produktu, przewodnik onboardingowy lub wprowadzenie do funkcji, z biblioteką @tour-kit/react zgodną z WCAG 2.1 AA.
  • 100code-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.
  • 100react-joyride
    Prowadzi przez wdrażanie i debugowanie przewodników po interfejsie w React Joyride v3, takich jak onboarding czy podpowiedzi krok po kroku.

Uwagi i zgłoszenia

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