/skill

Code Tour

Credit: This skill comes from ECC. Keep this credit when you share or change the skill.

Create a CodeTour .tour file that guides a reader through a codebase. Save it in .tours/.

Each step must point to a real file and line. Each note must say:

• What the reader is seeing
• Why it matters
• Where to go next

Create only the .tour file. Do not change source code.

When to Use

Use this skill when the user asks for:

• A code tour
• A new team member tour
• A system design tour
• A pull request tour
• A root cause review tour
• A saved guide that explains how code works

Use it when a clear path through the code is better than a short summary.

When Not to Use

Steps

1. Read the Request

Find the main goal. Work out who will read the tour.

If the goal or reader is not clear, ask one short question. If you can make a safe guess, state the guess in the tour title or first step.

2. Study the Code

Before writing the tour, check:

• The README
• The main app or package start file
• The folder layout
• Config files tied to the topic
• Tests tied to the topic
• Changed files, if the tour is for a pull request
• Logs, fixes, and tests, if the tour is for a bug review

Do not write steps until you know the real code path.

3. Pick the Reader and Size

Use fewer steps when the code path is small. Do not add weak steps just to meet a count.

4. Plan the Path

Put steps in a useful order. A common path is:

1. Start file
2. Main call
3. Key data type
4. Core work
5. Saved data or outside service
6. Error path
7. Test

For a pull request, start with the reason for the change. Then show the main change, its callers, and its tests.

For a bug review, show the bad input, the failing path, the root cause, the fix, and the test that stops the bug from coming back.

5. Check Every Link

Each step must point to:

• A file that exists
• A line that exists
• The first useful line for that step

Use paths from the project root. Use /, even on Windows.

Do not point to blank lines, closing marks, or comments that do not show the idea.

If lines may move, point to the first line of a named function, class, route, or setting. Keep the note clear enough that the reader can still find the code.

If a file is made during a build, point to the source file instead. Skip vendor files, lock files, and large made files unless they are the main topic.

If no good line exists, leave that step out. Do not make up a file or line.

6. Write the File

Save the tour as .tours/<clear-name>.tour.

Use lowercase words and hyphens in the file name, such as:

user-login-flow.tour

A .tour file is JSON. Use this shape:

{
  "title": "How user login works",
  "description": "A short tour for a new developer.",
  "steps": [
    {
      "file": "src/server.ts",
      "line": 18,
      "description": "The app starts here. It adds the login routes. Next, open the route file to see how a login request is handled."
    },
    {
      "file": "src/routes/login.ts",
      "line": 24,
      "description": "This handler reads the email and password. It then asks the auth service to check them."
    }
  ]
}

Use valid JSON:

• Use double quotes
• Do not add comments
• Do not add a comma after the last item
• Use a positive whole number for each line
• Keep steps in reading order

7. Review the Tour

Before you finish, check that:

• The JSON can be read
• The file is inside .tours/
• Every file exists
• Every line is valid
• Each step adds new value
• The path matches the real code flow
• The first step gives the goal
• The last step gives a clear end point
• No source file was changed

Writing Rules

Keep each note short. Use two to four short sentences.

Name real code parts when useful. Do not copy large blocks of code into the note.

Explain links between steps. Do not write notes like “This is the service” or “Look at this file.” Say what the code does and why the reader should care.

Do not include secrets, keys, passwords, private user data, or full log records.

Example Request and Result

Request:

Make a pull request tour for the new password reset flow.

Good tour plan:

1. Start at the route added by the pull request.
2. Show how input is checked.
3. Show how the reset token is made.
4. Show where the token is saved.
5. Show how the email is sent.
6. Show the token check.
7. End at the test for an old or bad token.

Output one file:

.tours/password-reset-pr.tour

Do not also make a Markdown guide or change the password reset code.