All jobs

Add a Getting Started Walkthrough to a VS Code Extension

Yes. An agent reads your extension's commands and settings, contributes a walkthrough with steps that complete on real actions, packages the media, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent starts from the manifest. In an extension like usernamehw/vscode-error-lens, package.json declares version 3.30.0 for publisher usernamehw, requires vscode 1.107.0 or later, activates on onStartupFinished, and ships dist/extension.js as both main and browser, built by webpack through the vscode:prepublish script. Its contributes block has three keys: 17 commands in the Error Lens category, a configuration with 76 errorLens.* settings, and colors. There is no walkthroughs key. The README documents every command and setting in generated tables between COMMANDS_START and SETTINGS_START markers, and docs/docs.md opens by saying the inline message is the most annoying part of the extension and shows how to tame it, with screenshots under docs/img/ for followCursor, messageBackgroundMode, gutterIconsEnabled and the rest. .vscodeignore excludes docs, src and img/demo.png from the package, and the CHANGELOG.md entries carry release dates. A new user installs the extension, sees every line in red, and either finds docs/docs.md or uninstalls.

It writes the walkthrough into contributes.walkthroughs with one entry, id gettingStarted, a title and a short description, and five steps that follow the order docs/docs.md already uses. The first step shows what the extension does, with a packaged screenshot as media.image and alt text. The second, calming it down, links command:errorLens.toggleInlineMessage and the errorLens.followCursor setting and completes on onCommand:errorLens.toggleInlineMessage or onSettingChanged:errorLens.followCursor. The third picks severities with the four toggle commands and completes on onSettingChanged:errorLens.enabledDiagnosticLevels. The fourth covers the gutter and status bar settings. The fifth, for the two commands added in 3.30.0, errorLens.nextProblem and errorLens.prevProblem, suggests a keybinding and completes on onCommand:errorLens.nextProblem. Each step's description uses the command: link form VS Code renders as a button, so a step is done by doing the thing, not by reading about it.

Media has to be inside the package, and .vscodeignore currently drops docs entirely. The agent copies the screenshots the steps use into media/walkthrough/, keeps that directory out of the ignore list, and adds media/walkthrough/** nowhere else so npx @vscode/vsce ls shows exactly those files beside dist/extension.js, img/icon.png, README.md and CHANGELOG.md. Settings referenced in step text use the #errorLens.followCursor# form the existing configuration descriptions already use, which VS Code turns into a link to the setting. The README gets one line under Features pointing at the walkthrough through the Help: Welcome page, and the CHANGELOG is left for the maintainer, since its entries are dated at release.

The repository has no test script, so the agent proves the contribution two ways. npm ci and npm run vscode:prepublish show webpack still builds the bundle in production mode. Then it installs @vscode/test-electron as a dev dependency for the run only, downloads VS Code, and runs a small script that activates the extension and executes workbench.action.openWalkthrough with usernamehw.errorlens#gettingStarted, failing if the command rejects, which it does for an unknown walkthrough id or a malformed step. npx @vscode/vsce package --no-dependencies builds the .vsix and confirms the media paths resolve. The pull request keeps the test script in scripts/ as an optional check rather than wiring it into package.json, so the maintainer's build stays the same.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add a Getting Started walkthrough to this VS Code extension. Read package.json in full, README.md, CHANGELOG.md, docs/docs.md, .vscodeignore, .vscode/launch.json, src/extension.ts and src/commands.ts first. Contribute one walkthrough under contributes.walkthroughs with five steps that follow the order docs/docs.md uses: what the extension shows, calming the inline message with the toggle command and followCursor, choosing severities with the toggle commands, gutter and status bar settings, and the next and previous problem commands with a suggested keybinding. Use command: links in step descriptions and completionEvents on the real commands and settings. Copy the screenshots each step needs into media/walkthrough and make sure .vscodeignore keeps them in the package. Add one README line pointing at the walkthrough and leave the CHANGELOG alone. Run npm ci and npm run vscode:prepublish, package with vsce and list the packaged files, and run a script with @vscode/test-electron that activates the extension and opens the walkthrough by id so a bad id or step fails. Open a pull request that lists each step and its completion event.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that adds a walkthroughs contribution to package.json, a media/walkthrough/ directory with the screenshots the steps use, one line in README.md, and a scripts/ check that opens the walkthrough in a downloaded VS Code. The description lists the five steps, the command or setting each one completes on, and the files vsce ls reports in the package.

The run's record keeps the webpack output from vscode:prepublish, the vsce ls listing, and the output of the test-electron script with the walkthrough id it opened, so a reviewer sees the contribution is well formed without installing the .vsix first.

Before merging, a reviewer installs the packaged .vsix, opens Help: Welcome, picks the walkthrough, and clicks through each step, checking that the toggle step ticks itself when the inline message is toggled and that every image loads from the package rather than from the repository.

Run it on every Linear issue labelled onboarding

In the console, an automation with a linear trigger on linear.issue.labeled and the label onboarding starts one run per labelled issue in the Project's repository. The trigger adds the issue's text after the saved prompt, so an issue that asks for a step about a new setting or a shorter walkthrough carries that request itself and the prompt stays fixed. Changes made by an app integration never fire it, and the automation's max_runs_per_hour bounds a burst of labelling.

From your own server, the same job is one POST /o/{org}/sessions per issue, with the repository in resources and the issue's https://linear.app/<workspace>/issue/<ID> URL beside it so Rush reads the issue through your Linear connection. A webhook_url on the API key receives run.completed or run.failed for every run that key starts, with the session_url to read the pull request link from.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

A walkthrough is JSON that VS Code validates only when it loads the extension, and the usual mistakes, an image path the package does not contain, a completionEvents entry naming a command that does not exist, a settings link in the wrong form, show up as a blank step in the Welcome page rather than as a build error. The agent downloads VS Code into its own sandbox, loads the extension and opens the walkthrough by id, which a review of the diff cannot do.

The packaging check matters as much as the manifest: .vscodeignore in this extension excludes the whole docs tree, so a step that pointed at docs/img/ would render in the development host and break in the Marketplace build. The vsce ls output in the run's record shows the media files present, with the command that produced it.

Frequently asked questions

Will the walkthrough open on its own after install?

VS Code shows a new extension's walkthrough on the Welcome page after installation; it does not interrupt the editor. The agent does not call workbench.action.openWalkthrough from activate, because an extension that activates on onStartupFinished would then open the page on every start.

Can a step complete when the user changes a setting rather than runs a command?

Yes, through onSettingChanged: in completionEvents, which the calming and severity steps use for errorLens.followCursor and errorLens.enabledDiagnosticLevels. A step with no completion event completes when the user clicks it, which the first, descriptive step relies on.

Does this change the webpack build or the published bundle?

No. The contribution lives in package.json and the media directory; dist/extension.js is unchanged and vscode:prepublish runs exactly as before. The only packaging difference is the handful of images under media/walkthrough/ that vsce ls now lists.

What if a step references a command that is later renamed?

The step's button stops working and its completion never fires, with no build error. The test-electron script in scripts/ opens the walkthrough and can be extended to execute each command: link it finds, which is the regression check the pull request suggests adding to CI.

More VS Code Extension jobs

More jobs like this: Turn a Linear label into a PR

Keep reading