prompts/docs/skills/vscode-configuration/SKILL.md

name, description, argument-hint

name	description	argument-hint
vscode-configuration	Create and troubleshoot VS Code workspace configuration for Python projects, with focused patterns for launch.json debugpy/FastAPI debugging and tasks.json task automation.	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
• FastAPI-focused debug profiles using debugpy: FastAPI + debugpy launch patterns
• Task runner setup in VS Code: tasks.json project tasks

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.

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.

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.

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.