Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-04-14 20:25:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add code-tour skill — AI-generated CodeTour walkthroughs (#1277)

Browse Source 
* feat: add code-tour skill for AI-generated CodeTour walkthroughs

* fix: trim SKILL.md from 645 to 432 lines (under 500 limit)

Reduce persona table to top 10, condense verbose examples and notes,
trim redundant anti-patterns, compress step type docs and PR recipe.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: run npm run build to update README with code-tour skill

Addresses review feedback from @aaronpowell

* fix: add missing scripts/ and references/ files referenced in SKILL.md

Addresses reviewer feedback — SKILL.md referenced bundled files
(validate_tour.py, generate_from_docs.py, codetour-schema.json,
examples.md) that were not included in the PR.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: run npm run build to update skills README with new assets

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Srinivas Vaddi
2026-04-12 19:52:59 -04:00
committed by GitHub
parent 10fda505b7
commit 09049e3b78
6 changed files with 1376 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
skills/code-tour/references/codetour-schema.json Normal file
View File

@@ -0,0 +1,115 @@
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Schema for CodeTour tour files",
"type": "object",
"required": ["title", "steps"],
"properties": {
"title": {
"type": "string",
"description": "Specifies the title of the code tour."
},
"description": {
"type": "string",
"description": "Specifies an optional description for the code tour."
},
"ref": {
"type": "string",
"description": "Indicates the git ref (branch/commit/tag) that this tour associate with."
},
"isPrimary": {
"type": "boolean",
"description": "Specifies whether the tour represents the primary tour for this codebase."
},
"nextTour": {
"type": "string",
"description": "Specifies the title of the tour that is meant to follow this tour."
},
"stepMarker": {
"type": "string",
"description": "Specifies the marker that indicates a line of code represents a step for this tour."
},
"when": {
"type": "string",
"description": "Specifies the condition (JavaScript expression) that must be met before this tour is shown."
},
"steps": {
"type": "array",
"description": "Specifies the list of steps that are included in the code tour.",
"default": [],
"items": {
"type": "object",
"required": ["description"],
"properties": {
"title": {
"type": "string",
"description": "An optional title for the step."
},
"description": {
"type": "string",
"description": "Description of the step. Supports markdown."
},
"file": {
"type": "string",
"description": "File path (relative to the workspace root) that the step is associated with."
},
"directory": {
"type": "string",
"description": "Directory path (relative to the workspace root) that the step is associated with."
},
"uri": {
"type": "string",
"description": "Absolute URI (https://...) associated with the step. Use for PRs, issues, docs, ADRs."
},
"line": {
"type": "number",
"description": "Line number (1-based) that the step is associated with."
},
"pattern": {
"type": "string",
"description": "Regex to associate the step with a line by content instead of line number. Useful when line numbers shift frequently."
},
"selection": {
"type": "object",
"required": ["start", "end"],
"description": "Text selection range associated with the step. Use when a block of code (not a single line) is the point.",
"properties": {
"start": {
"type": "object",
"required": ["line", "character"],
"properties": {
"line": { "type": "number", "description": "Line number (1-based) where the selection starts." },
"character": { "type": "number", "description": "Column number (1-based) where the selection starts." }
}
},
"end": {
"type": "object",
"required": ["line", "character"],
"properties": {
"line": { "type": "number", "description": "Line number (1-based) where the selection ends." },
"character": { "type": "number", "description": "Column number (1-based) where the selection ends." }
}
}
}
},
"view": {
"type": "string",
"description": "VS Code view ID to auto-focus when navigating to this step (e.g. 'terminal', 'explorer', 'problems', 'scm')."
},
"commands": {
"type": "array",
"description": "VS Code command URIs to execute when this step is navigated to.",
"default": [],
"items": { "type": "string" },
"examples": [
["editor.action.goToDeclaration"],
["workbench.action.terminal.focus"],
["editor.action.showHover"],
["references-view.findReferences"],
["workbench.action.tasks.runTask"]
]
}
}
}
}
}
}

195
skills/code-tour/references/examples.md Normal file
View File

@@ -0,0 +1,195 @@
# Real-World CodeTour Examples
Reference this file when you want to see how real repos use CodeTour features.
Each example is sourced from a public GitHub repo with a direct link to the `.tour` file.
---
## microsoft/codetour — Contributor orientation
**Tour file:** https://github.com/microsoft/codetour/blob/main/.tours/intro.tour
**Persona:** New contributor
**Steps:** ~5 · **Depth:** Standard
**What makes it good:**
- Intro step with an embedded SVG architecture diagram (raw GitHub URL inside the description)
- Rich markdown per step with emoji section headers (`### 🎥 Tour Player`)
- Inline cross-file links inside descriptions: `[Gutter decorator](./src/player/decorator.ts)`
- Uses the top-level `description` field as a subtitle for the tour itself
**Technique to copy:** Embed images and cross-links in descriptions to make them self-contained.
```json
{
"file": "src/player/index.ts",
"line": 436,
"description": "### 🎥 Tour Player\n\nThe CodeTour player ...\n\n![Architecture](https://raw.githubusercontent.com/.../overview.svg)\n\nSee also: [Gutter decorator](./src/player/decorator.ts)"
}
```
---
## a11yproject/a11yproject.com — New contributor onboarding
**Tour file:** https://github.com/a11yproject/a11yproject.com/blob/main/.tours/code-tour.tour
**Persona:** External contributor
**Steps:** 26 · **Depth:** Deep
**What makes it good:**
- Almost entirely `directory` steps — orients to every `src/` subdirectory without getting lost in files
- Conversational, beginner-friendly tone throughout
- `selection` on the opening step to highlight the exact entry in `package.json`
- Closes with a genuine thank-you and call-to-action
**Technique to copy:** Use directory steps as the skeleton of an onboarding tour — they teach structure without requiring the author to explain every file.
```json
{
"directory": "src/_data",
"description": "This folder contains the **data files** for the site. Think of them as a lightweight database — YAML files that power the resource listings, posts index, and nav."
}
```
---
## github/codespaces-codeql — The most technically complete example
**Tour file:** https://github.com/github/codespaces-codeql/blob/main/.tours/codeql-tutorial.tour
**Persona:** Security engineer / concept learner
**Steps:** 12 · **Depth:** Standard
**What makes it good:**
- `isPrimary: true` — auto-launches when the Codespace opens
- `commands` array to run real VS Code commands mid-tour: the tour literally executes `codeQL.runQuery` when the reader arrives at that step
- `view` property to switch the sidebar panel (`"view": "codeQLDatabases"`)
- `pattern` instead of `line` for resilient matching: `"pattern": "import tutorial.*"`
- `selection` to highlight the exact `select` clause in a query file
**This is the canonical reference for `commands`, `view`, and `pattern`.**
```json
{
"file": "tutorial.ql",
"pattern": "import tutorial.*",
"view": "codeQLDatabases",
"commands": ["codeQL.setDefaultTourDatabase", "codeQL.runQuery"],
"title": "Run your first query",
"description": "Click the **▶ Run** button above. The results appear in the CodeQL Query Results panel."
}
```
---
## github/codespaces-learn-with-me — Minimal interactive tutorial
**Tour file:** https://github.com/github/codespaces-learn-with-me/blob/main/.tours/main.tour
**Persona:** Total beginner
**Steps:** 4 · **Depth:** Quick
**What makes it good:**
- Only 4 steps — proves that less is more for quick/vibecoder personas
- `isPrimary: true` for auto-launch
- Each step tells the reader to **do something** (edit a string, change a color) — not just read
- Ends with a tangible outcome: "your page is live"
**Technique to copy:** For quick/vibecoder tours, cut mercilessly. Four steps that drive action beat twelve that explain everything.
---
## blackgirlbytes/copilot-todo-list — 28-step interactive tutorial
**Tour file:** https://github.com/blackgirlbytes/copilot-todo-list/blob/main/.tours/main.tour
**Persona:** Concept learner / hands-on tutorial
**Steps:** 28 · **Depth:** Deep
**What makes it good:**
- Uses **content-only checkpoint steps** (no `file` key) as progress milestones: "Check out your page! 🎉" and "Try it out!" between coding tasks
- Terminal inline commands in descriptions: `>> npm install uuid; npm install styled-components`
- Each file step shows the exact code the user should accept, in a markdown code fence, so they know the expected output
**Technique to copy:** Checkpoint steps (content-only, milestone title) break up long tours and give the reader a sense of progress.
```json
{
"title": "Check out your page! 🎉",
"description": "Open the **Simple Browser** tab to see your to-do list. You should see all three tasks rendering from your data array.\n\nOnce you're happy with it, continue to add interactivity."
}
```
---
## lucasjellema/cloudnative-on-oci-2021 — Multi-tour architecture series
**Tour files:**
- https://github.com/lucasjellema/cloudnative-on-oci-2021/blob/main/.tours/function-tweet-retriever.tour
- https://github.com/lucasjellema/cloudnative-on-oci-2021/blob/main/.tours/oci-and-infrastructure-as-code.tour
- https://github.com/lucasjellema/cloudnative-on-oci-2021/blob/main/.tours/build-and-deployment-pipeline-function-tweet-retriever.tour
**Persona:** Platform engineer / architect
**Steps:** 12 per tour · **Depth:** Standard
**What makes it good:**
- Three separate tours for three separate concerns (function code, IaC, CI/CD pipeline) — each standalone but linked via `nextTour`
- `selection` coordinates used heavily in Terraform files where a block (not a single line) is the point
- Steps include markdown links to official OCI documentation inline
- Designed to be browsed via `vscode.dev/github.com/...` without cloning
**Technique to copy:** For complex systems, write one tour per layer and chain them with `nextTour`. Don't try to cover infrastructure + application code + CI/CD in one tour.
---
## SeleniumHQ/selenium — Monorepo build system onboarding
**Tour files:**
- `.tours/bazel.tour` — Bazel workspace and build target orientation
- `.tours/building-and-testing-the-python-bindings.tour` — Python bindings BUILD.bazel walkthrough
**Persona:** External contributor (build system focus)
**Steps:** ~10 per tour
**What makes it good:**
- Targets a non-obvious entry point — not the product code but the build system
- Proves that "contributor onboarding" tours don't have to start with `main()` — they start with whatever is confusing about this specific repo
- Used in a large, mature OSS project at scale
---
## Technique quick-reference
| Feature | When to use | Real example |
|---------|-------------|-------------|
| `isPrimary: true` | Auto-launch tour when repo opens (Codespace, vscode.dev) | codespaces-learn-with-me, codespaces-codeql |
| `commands: [...]` | Run a VS Code command when reader arrives at this step | codespaces-codeql (`codeQL.runQuery`) |
| `view: "terminal"` | Switch VS Code sidebar/panel at this step | codespaces-codeql (`codeQLDatabases`) |
| `pattern: "regex"` | Match by line content, not number — use for volatile files | codespaces-codeql |
| `selection: {start, end}` | Highlight a block (function body, config section, type def) | a11yproject, oci-2021, codespaces-codeql |
| `directory: "path/"` | Orient to a folder without reading every file | a11yproject, codespaces-codeql |
| `uri: "https://..."` | Link to PR, issue, RFC, ADR, external doc | Any PR review tour |
| `nextTour: "Title"` | Chain tours in a series | oci-2021 (3-part series) |
| Checkpoint steps (content-only) | Progress milestones in long interactive tours | copilot-todo-list |
| `>> command` in description | Terminal inline command link in VS Code | copilot-todo-list |
| Embedded image in description | Architecture diagrams, screenshots | microsoft/codetour |
---
## Discover more real tours on GitHub
**Search all `.tour` files on GitHub:**
https://github.com/search?q=path%3A**%2F*.tour+&type=code
This search returns every `.tour` file committed to a public GitHub repo. Use it to:
- Find tours for repos in the same language/framework as the one you're working on
- Study how other authors handle the same personas or step types
- Look up how a specific field (`commands`, `selection`, `pattern`) is used in the wild
Filter by language or keyword to narrow results — e.g. add `language:TypeScript` or `fastapi` to the query.
---
## Further reading
- **DEV Community — "Onboard your codebase with CodeTour"**: https://dev.to/tobiastimm/onboard-your-codebase-with-codetour-2jc8
- **Coder Blog — "Onboard to new projects faster with CodeTour"**: https://coder.com/blog/onboard-to-new-projects-faster-with-codetour
- **Microsoft Tech Community — Educator Developer Blog**: https://techcommunity.microsoft.com/blog/educatordeveloperblog/codetour-vscode-extension-allows-you-to-produce-interactive-guides-assessments-a/1274297
- **AMIS Technology Blog — vscode.dev + CodeTour**: https://technology.amis.nl/software-development/visual-studio-code-the-code-tours-extension-for-in-context-and-interactive-readme/
- **CodeTour GitHub Topics**: https://github.com/topics/codetour