john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

vscode skill

Browse Source
This commit is contained in:
John Lancaster
2026-06-19 16:56:45 -05:00
parent 45d8beda8a
commit 75b0c8d192
9 changed files with 434 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/skills/vscode-configuration/SKILL.md
+95
View File
@@ -0,0 +1,95 @@
---
name: vscode-configuration
description: 'Create and troubleshoot VS Code workspace configuration for Python projects, with focused patterns for launch.json debugpy/FastAPI debugging and tasks.json task automation.'
argument-hint: 'What do you need: debug setup, FastAPI debug run profile, tasks.json automation, or all of them?'
---
# VS Code Configuration
Use this skill to design or repair repeatable VS Code workspace configuration for local development workflows.
## When to Use
- You need to create or fix `.vscode/launch.json` debug profiles.
- You need robust Python debugging with `debugpy`.
- You need FastAPI-specific launch profiles (app module, host/port, reload options, env files).
- You need `.vscode/tasks.json` build/test/run tasks and optional debug pre-launch integration.
- You need consistent workspace onboarding where users can run and debug from VS Code with minimal manual setup.
## Progressive References
Load only the page that matches the current request:
- Launch profile mechanics and debugpy patterns: [debug launch configurations](./references/debug-launch-configurations.md)
- FastAPI-focused debug profiles using debugpy: [FastAPI + debugpy launch patterns](./references/fastapi-debugpy-launch.md)
- Task runner setup in VS Code: [tasks.json project tasks](./references/tasks-json-configuration.md)
## Procedure
### Step 1: Capture the Runtime Shape
Collect the minimum context before writing files:
1. Python entry shape: module path vs script path.
2. Framework runtime: plain script, FastAPI with uvicorn, or mixed services.
3. Required environment: env file, env vars, cwd, and PYTHONPATH needs.
4. Task expectations: run app, run tests, lint/format, one-off setup.
Completion check: you can state exactly what command should run for debug and for task execution.
### Step 2: Create launch.json Profiles
1. Add at least one stable baseline profile before specialized variants.
2. Prefer module-based launches where packaging/import paths matter.
3. Keep debugger options explicit (`justMyCode`, `console`, `cwd`, `envFile`).
4. Add purpose-built profiles instead of one overloaded profile.
For concrete patterns, open [debug launch configurations](./references/debug-launch-configurations.md).
Completion check: selecting each profile starts the intended process without manual edits.
### Step 3: Add FastAPI Profiles When Needed
1. Use a dedicated FastAPI profile that launches `uvicorn` via module mode.
2. Keep host/port/reload/log-level as explicit args.
3. Include `jinja` debugging only if templates are in scope.
4. Add an attach profile when launching via external `debugpy` listener.
For complete examples, open [FastAPI + debugpy launch patterns](./references/fastapi-debugpy-launch.md).
Completion check: breakpoints hit in app code and startup path, and profile behavior matches dev vs non-dev expectations.
### Step 4: Add tasks.json for Repeated Commands
1. Create named tasks for run, test, lint, and docs/build steps as needed.
2. For Python projects, keep commands consistent with the repo package manager.
3. Use `problemMatcher` where parsers exist and background flags for long-running tasks.
4. Link debug profiles to tasks with `preLaunchTask` only when startup sequencing is required.
For task schema and examples, open [tasks.json project tasks](./references/tasks-json-configuration.md).
Completion check: tasks run from Command Palette and can be reused by debug profiles.
### Step 5: Validate End-to-End
1. Run each launch profile once.
2. Run each task once.
3. Verify paths, env files, and interpreter assumptions on a clean workspace reload.
4. Record any project-specific defaults in comments or docs if non-obvious.
Completion check: a teammate can clone the repo, open VS Code, and run/debug with only documented prerequisites.
## Decision Points
- If the app is imported as a package, prefer module launches over direct script paths.
- If runtime is started outside VS Code, add attach profile instead of forcing launch mode.
- If there are long-running dev servers, pair with background tasks.
- If test command differs by repo convention, mirror that command in tasks exactly.
## Output Contract
Return:
1. Created or updated VS Code config files and profile/task names.
2. Any assumptions (module path, env file, command runner).
3. Validation results and any unresolved decisions.
docs/skills/vscode-configuration/references/debug-launch-configurations.md
+101
View File
@@ -0,0 +1,101 @@
# Debug Launch Configurations in VS Code
This reference focuses on Python debugging through `debugpy` using `.vscode/launch.json`.
## Core Structure
A minimal launch file:
```json
{
"version": "0.2.0",
"configurations": []
}
```
Useful fields for Python configs:
- `type`: Use `debugpy`.
- `request`: Usually `launch`, sometimes `attach`.
- `name`: Friendly profile name shown in the Run and Debug panel.
- `program`: Script path for script-based entry.
- `module`: Module name for `python -m ...` style launches.
- `args`: CLI arguments.
- `cwd`: Working directory.
- `env` / `envFile`: Environment variables.
- `console`: `integratedTerminal` is usually most practical.
- `justMyCode`: `true` by default; set `false` when stepping into dependencies.
## Launch vs Attach
Use `launch` when VS Code should start the process.
Use `attach` when the process already runs with debugpy listening.
Attach profile example:
```json
{
"name": "Python: Attach (debugpy :5678)",
"type": "debugpy",
"request": "attach",
"connect": {
"host": "127.0.0.1",
"port": 5678
},
"justMyCode": true
}
```
Remote process side command example:
```bash
python -m debugpy --listen 5678 -m your_package.main
```
## Script and Module Patterns
Script pattern:
```json
{
"name": "Python: Script",
"type": "debugpy",
"request": "launch",
"program": "${workspaceFolder}/src/app.py",
"cwd": "${workspaceFolder}",
"console": "integratedTerminal",
"justMyCode": true
}
```
Module pattern:
```json
{
"name": "Python: Module",
"type": "debugpy",
"request": "launch",
"module": "your_package.main",
"cwd": "${workspaceFolder}",
"console": "integratedTerminal",
"justMyCode": true
}
```
Prefer module mode when imports depend on package layout.
## Environment and Interpreter Notes
- Use `envFile` for shared local variables, commonly `${workspaceFolder}/.env`.
- Keep secrets out of committed launch configs.
- Ensure the selected VS Code interpreter matches project tooling.
## Troubleshooting
If breakpoints do not hit:
1. Confirm the right profile is selected.
2. Confirm the file path/module path is correct.
3. Disable `justMyCode` temporarily to inspect call flow.
4. Confirm no stale background process is occupying the expected port.
5. Confirm workspace root and `cwd` align with imports.
docs/skills/vscode-configuration/references/fastapi-debugpy-launch.md
+98
View File
@@ -0,0 +1,98 @@
# FastAPI Debug Launch with debugpy
This reference provides practical `.vscode/launch.json` patterns for FastAPI applications started with uvicorn.
## Launch FastAPI via Module
Preferred profile:
```json
{
"name": "FastAPI: Uvicorn (debug)",
"type": "debugpy",
"request": "launch",
"module": "uvicorn",
"args": [
"your_package.main:app",
"--host",
"127.0.0.1",
"--port",
"8000",
"--reload",
"--log-level",
"debug"
],
"cwd": "${workspaceFolder}",
"envFile": "${workspaceFolder}/.env",
"console": "integratedTerminal",
"justMyCode": true,
"jinja": true
}
```
Why module mode: it matches `python -m uvicorn ...` behavior and avoids path ambiguity.
## Launch with Factory Pattern
If app is created via factory function:
```json
{
"name": "FastAPI: Uvicorn factory (debug)",
"type": "debugpy",
"request": "launch",
"module": "uvicorn",
"args": [
"your_package.main:create_app",
"--factory",
"--host",
"127.0.0.1",
"--port",
"8000",
"--reload"
],
"cwd": "${workspaceFolder}",
"console": "integratedTerminal",
"justMyCode": true
}
```
## Attach to an Existing FastAPI Process
If the app is launched externally, start with debugpy:
```bash
python -m debugpy --listen 5678 -m uvicorn your_package.main:app --host 127.0.0.1 --port 8000 --reload
```
Attach profile:
```json
{
"name": "FastAPI: Attach (5678)",
"type": "debugpy",
"request": "attach",
"connect": {
"host": "127.0.0.1",
"port": 5678
},
"justMyCode": true
}
```
## Common FastAPI Debug Pitfalls
1. Wrong import target in `your_package.main:app` or factory symbol.
2. `cwd` does not match source layout.
3. Auto-reload creating confusion about active process when breakpoints are set in startup code.
4. Port collisions from old uvicorn processes.
5. Environment variables not loaded because `envFile` path is wrong.
## Practical Quality Gate
A profile is considered valid when:
1. Server starts from VS Code Run and Debug.
2. A breakpoint inside an endpoint is hit on request.
3. A breakpoint in startup/lifespan logic is hit at app boot.
4. Terminal output appears in integrated terminal with expected log level.
docs/skills/vscode-configuration/references/tasks-json-configuration.md
+92
View File
@@ -0,0 +1,92 @@
# Configure Project Tasks in tasks.json
Use `.vscode/tasks.json` to define repeatable project commands and optional hooks for debugging.
## Minimal File
```json
{
"version": "2.0.0",
"tasks": []
}
```
## Task Fields You Will Use Most
- `label`: Task name shown in VS Code.
- `type`: Usually `shell`.
- `command`: Executable to run.
- `args`: Command arguments.
- `options.cwd`: Working directory.
- `group`: Mark default build or test tasks.
- `problemMatcher`: Parse errors into the Problems panel.
- `isBackground`: `true` for long-running tasks (for example dev server watch).
## Python Project Example
```json
{
"version": "2.0.0",
"tasks": [
{
"label": "App: Run",
"type": "shell",
"command": "uv",
"args": ["run", "uvicorn", "personal_mcp.main:app", "--host", "127.0.0.1", "--port", "8000", "--reload"],
"options": {
"cwd": "${workspaceFolder}"
},
"isBackground": true,
"problemMatcher": []
},
{
"label": "Tests: Pytest",
"type": "shell",
"command": "uv",
"args": ["run", "pytest"],
"options": {
"cwd": "${workspaceFolder}"
},
"group": "test",
"problemMatcher": []
}
]
}
```
## Connect Tasks to Debug Profiles
In `launch.json`, you can run a task first:
```json
{
"name": "FastAPI: Attach",
"type": "debugpy",
"request": "attach",
"connect": {
"host": "127.0.0.1",
"port": 5678
},
"preLaunchTask": "App: Run"
}
```
Use this only when startup sequencing is needed.
## Task Design Guidelines
1. Keep labels stable and descriptive.
2. Prefer one task per intent instead of monolithic shell commands.
3. Keep shell portability in mind if teammates use multiple OSes.
4. Avoid embedding secrets directly in task definitions.
5. Mark long-running tasks with `isBackground` and keep matchers explicit.
## Troubleshooting
If a task fails unexpectedly:
1. Run the underlying command directly in terminal.
2. Confirm `options.cwd` points to expected workspace root.
3. Confirm tool availability in environment path.
4. Confirm quoting and argument boundaries in `args`.
5. Confirm the task is not blocked by an outdated background process.