publish-vscode-extension

Files (12)

• SKILL.md
• evals.json · evals/
• publish-error.log · evals/files/ci-logs/
• package.json · evals/files/fastbelt-vscode/
• README.md · evals/files/langium-vscode/
• package.json · evals/files/langium-vscode/
• package.json · evals/files/open-collaboration-vscode/
• package.json · evals/files/unbundled-markdown-toolkit/
• bundling.md · references/
• manifest.md · references/
• open-vsx.md · references/
• vscode-marketplace.md · references/

SKILL.md (first lines)

# Publish a VS Code extension

There are two registries where VS Code extensions live:

- **VS Code Marketplace** — Microsoft's registry. Consumed by VS Code, Visual Studio, and Azure DevOps. Authenticated with an Azure DevOps Personal Access Token (PAT). Tooling: `@vscode/vsce`.
- **Open VSX Registry** — the Eclipse Foundation's open-source registry at https://open-vsx.org. Consumed by VS Codium, Theia-based IDEs, Cursor, Windsurf, code-server, and most non-Microsoft forks. Authenticated with a token issued by open-vsx.org after accepting the Eclipse Publisher Agreement. Tooling: `ovsx`.

Most production extensions publish to **both**. The same `.vsix` works on either registry — *package once, publish twice*. Don't publish only to Marketplace; non-Microsoft VS Code distributions can't see those extensions.

## Branches

Match the user's intent — most sessions are **prepare**, not publish:

- **Prepare or audit** — manifest, README, CHANGELOG, bundling, registry identity, CI workflow. Work only the relevant sections below; do not run publish commands or ask for tokens unless the user asks to publish.
- **Publish now** — only when the user wants an agent-driven or one-off publish in this session. Prefer **CI** (see Typical CI release flow); local `vsce`/`ovsx` is the exception.

### Publish sequence (publish-now only)

Follow in order; do not skip ahead until each step's **done when** is met:

1. **Decide registries** — default both unless proprietary Marketplace-only APIs block Open VSX. *Done when:* you've told the user which registries you're targeting.
2. **Prepare** — manifest, supporting files, build deps. *Done when:* required manifest fields and README/LICENSE/CHANGELOG are in place (see below).
3. **Package** — `vsce package`, then inspect with `vsce ls`. *Done when:* `<name>-<version>.vsix` exists and the file list has no `src/`, `.git/`, or full `node_modules/` tree.
4. **Confirm tokens** — env vars for each target registry; never use values pasted in chat. *Done when:* needed vars are set in this shell (check with `[ -n "$VSCE_PAT" ]` / `[ -n "$OVSX_PAT" ]` without printing values) and the user has publisher/namespace identity on each registry (ask before minting tokens if unknown).
5. **Publish** — upload that same `.vsix` to each registry. *Done when:* every target `vsce publish --packagePath …` / `ovsx publish …` exits 0.

## Publish responsibly

VS Code extensions are **not sandboxed** — they run with the IDE's full privileges (files, processes, network). A publish token lets anyone push code that auto-updates on every install. Treat publishing like deploying malware-capable software: release from CI on protected branches/tags, not from a laptop; minimize activation scope and dependencies; and assume a stolen token is a full compromise until revoked.

When more context is needed, load:

- `references/manifest.md` — the full `package.json` extension manifest: every required, recommended, and runtime field, the allowed `categories` list, marketplace presentation fields (`galleryBanner`, `preview`, `badges`, `pricing`, `sponsor`, `qna`), runtime fields (`main`, `browser`, `activationEvents`, `contributes`, `capabilities`, `extensionKind`), dependency fields (`extensionDependencies`, `extensionPack`), validation gotchas, and a security review checklist. Read whenever you're editing `package.json`, troubleshooting "field X was rejected" errors, or auditing an unfamiliar extension's manifest.
- `references/vscode-marketplace.md` — Azure DevOps PAT, publisher creation, `vsce` commands, verified publisher, unpublishing, common 401/403 errors. Read whenever a step involves Marketplace authentication, publisher identity, or `vsce`-specific flags.
- `references/open-vsx.md` — Eclipse account setup, the Publisher Agreement, access tokens, namespace ownership and the "unverified" warning, `ovsx` commands, CI integration. Read whenever a step involves Open VSX, namespaces, or `ovsx`.
- `references/bundling.md` — why and how to bundle the extension with esbuild or webpack, wiring into `vscode:prepublish`, externalizing the `vscode` module, Web Extension targets, `.vscodeignore` for bundled extensions. Read whenever the extension isn't bundled yet, ships to Web hosts (`vscode.dev`, `github.dev`), is unexpectedly large, or has a slow activation time.

## Decide what to publish to

If the user hasn't said, default to **both** registries and tell them. Only skip Open VSX if the extension explicitly depends on proprietary Marketplace-only APIs or telemetry inappropriate for open-source distributions — and even then, say so explicitly.

## Prerequisites that apply to both registries

Install Node.js, then install the publishing CLIs:

```bash
npm install -g @vscode/vsce ovsx
```

`vsce` (the "VS Code Extension manager") is the canonical packager. `ovsx` reuses `vsce` internally for packaging-from-source, so installing both is the normal setup. `npx @vscode/vsce` / `npx ovsx` also work if you'd rather not install globally.

## Prepare the extension

Before publishing anywhere, make sure the extension is publish-ready. These are the same requirements for both registries — the registries reject or downrank extensions that fail them.

### `package.json` manifest

A minimal publish-ready manifest looks like:

```json
{
  "name": "extension-name",
  "displayName": "Human Readable Name",
  "description": "One sentence about what this extension does",
  "version": "0.0.1",
  "publisher": "<publisher-id-or-namespace>",
  "engines": { "vscode": "^1.84.0" },
  "categories": ["Other"],
  "keywords": ["tag1", "tag2"],
  "icon": "icon.png",
  "repository": { "type": "git", "url": "https://github.com/user/repo" },
  "license": "MIT",
  "bugs": { "url": "https://github.com/user/repo/issues" },
  "homepage": "https://github.com/user/repo#readme"
}
```

Four required fields: `name`, `version`, `publisher`, `engines.vscode`. Everything else is technically optional but the registry listing will look broken without `displayName`, `description`, `categories`, `icon`, `repository`, and `license`.

Two cross-cutting things to know up front:

- `publisher` is the same string on both registries by convention, but they're two independent identity systems — registering `acme` on Marketplace does *not* reserve `acme` on Open VSX, and vice versa. Register both names early to avoid squatters.
- `engines.vscode` must be a real published VS Code version range (e.g. `^1.84.0`). Wildcards (`*`) are rejected.

For every other field and validation gotcha, read `references/manifest.md`.

### Supporting files

- `README.md` — rendered as the extension's marketplace landing page on both registries. Images in it **must use absolute HTTPS URLs**, not relative paths (the registries serve the README from a different origin).
- `LICENSE` — required for unambiguous licensing. Match the `license` field in `package.json` (SPDX identifier like `MIT`, `Apache-2.0`).
- `CHANGELOG.md` — rendered as the "Changelog" tab. Conventional format is Keep-a-Changelog.
- `.vscodeignore` — exclude files from the `.vsix` (glob per line). Source TypeScript, tests, configs, and `node_modules/` dev deps should not ship. Example:
  ```
  .vscode/**
  .vscode-test/**
  src/**
  .gitignore
  .yarnrc
  vsc-extension-quickstart.md
  **/tsconfig.json
  **/.eslintrc.json
  **/*.map
  **/*.ts
  !out/**/*.js
  ```
  `vsce` automatically excludes `devDependencies` declared in `package.json`, so you don't need to list them.

### Build dependencies

Extensions are npm projects — `vsce package` runs `vscode:prepublish`, which executes whatever the build pulls in. Commit `package-lock.json` and run **`npm ci`** in CI (not `npm install`). Consider project-level `.npmrc` with `ignore-scripts=true` during install to block lifecycle-hook attacks; re-enable only if the build genuinely needs install scripts. Verify AI-suggested npm packages exist on the registry before adding them.

## Package once

Build the `.vsix` from the extension root:

```bash
vsce package
```

From TypeFox/agent-skills, MIT.

More from TypeFox/agent-skills