diff --git a/README.md b/README.md
index 0a1f0935..992d200f 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,8 @@ Here is where you can find the source code for various parts of the Quarto syste
 
 ## Development
 
+### VS Code Extension
+
 To develop the Quarto VS Code extension, clone this repo, run `yarn`, then run the `yarn dev-vscode` command:
 
 ```bash
@@ -22,5 +24,4 @@ yarn dev-vscode  # run development/debug version of extension
 
 Use the VS Code **Run and Debug** pane in the activity bar to run a version of VS Code with the development build of the extension.
 
-
-
+See our [`CONTRIBUTING`]((https://github.com/quarto-dev/quarto/blob/main/apps/vscode/CONTRIBUTING.md)) file for more information
diff --git a/apps/vscode/CONTRIBUTING.md b/apps/vscode/CONTRIBUTING.md
new file mode 100644
index 00000000..4a9960e2
--- /dev/null
+++ b/apps/vscode/CONTRIBUTING.md
@@ -0,0 +1,36 @@
+# Building the extension
+
+To develop the Quarto VS Code extension, clone the quarto mono-repo, run `yarn` at top level, then run the `yarn dev-vscode` command:
+
+```sh
+yarn             # install dependencies
+yarn dev-vscode  # run development/debug version of extension
+```
+
+Install the dev version of the extension in VS Code or Positron with:
+
+```sh
+yarn install-vscode
+yarn install-positron
+```
+
+
+# Debugging the extension
+
+The extension must have been built in dev mode (see the build section). The `dev` build flag is essential for debugging:
+
+- It disables minifying and generates source maps from generated JS files to source TS files. The source maps allow you to set breakpoints in our TS files and step through them.
+
+- It causes the LSP node process to be spawned in debug mode. This allows VS Code or another debugger to connect to the LSP via a special port.
+
+Here is the process:
+
+- Let `yarn dev-vscode` run in the background somewhere.
+
+- Open the `apps/vscode` folder in VS Code or Positron and go to the `Run and debug` pane.
+
+- Run the `Run VS Code Extension` to open the dev version of the extension in a new window.
+
+- If you need to set breakpoints in the LSP, you'll have to select the launch configuration `Attach to VS Code LSP server` and run that as well. You should see your LSP breakpoints bind (go from grayed out to red dots) as soon as the debugger is attached to the LSP.
+
+  Note that if you close the dev window and stop the extension debugging session, you'll have to manually close the LSP debugging session.
diff --git a/apps/vscode/package.json b/apps/vscode/package.json
index 83c30344..2d1a2832 100644
--- a/apps/vscode/package.json
+++ b/apps/vscode/package.json
@@ -1408,6 +1408,8 @@
   },
   "scripts": {
     "vscode:prepublish": "rm -rf ./out/markdownit && cd ../.. && turbo run build --force --filter quarto...",
+    "install-vscode": "rm -rf *.vsix && vsce package && code --install-extension *.vsix",
+    "install-positron": "rm -rf *.vsix && vsce package && positron --install-extension *.vsix",
     "build": "tsx build.ts",
     "dev": "yarn run build dev",
     "lint": "eslint src --ext ts",
diff --git a/package.json b/package.json
index b775476d..e88c29c5 100644
--- a/package.json
+++ b/package.json
@@ -11,6 +11,8 @@
     "build": "turbo run build",
     "dev-writer": "turbo run dev --filter writer*",
     "dev-vscode": "turbo run dev --filter quarto...",
+    "install-vscode": "cd apps/vscode && yarn install-vscode",
+    "install-positron": "cd apps/vscode && yarn install-positron",
     "lint": "turbo run lint",
     "format": "prettier --write \"**/*.{ts,tsx}\"",
     "watch": "concurrently 'tsc --watch --noEmit --project apps/writer/tsconfig.json' 'tsc --watch --noEmit  --project packages/writer-server/tsconfig.json'"