vscode skill

2026-06-19 16:56:45 -05:00
parent 45d8beda8a
commit 75b0c8d192
9 changed files with 434 additions and 1 deletions
@@ -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.