---
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?'
x-personal-mcp:
  id: vscode-configuration
  version: 1.0.0
  tags:
    - vscode
    - launch-json
    - tasks-json
    - debugpy
    - fastapi
    - python
    - skills
  capabilities:
    - resource://skills/vscode-configuration/document
  depends_on: []
  references:
    debug-launch-configurations:
      path: references/debug-launch-configurations.md
      mime_type: text/markdown
      title: Debug Launch Configurations
    fastapi-debugpy-launch:
      path: references/fastapi-debugpy-launch.md
      mime_type: text/markdown
      title: FastAPI Debugpy Launch
    tasks-json-configuration:
      path: references/tasks-json-configuration.md
      mime_type: text/markdown
      title: Tasks JSON Configuration
---

# 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.