consolidated new-skill resource

docs/new_skill.md

@@ -1,129 +0,0 @@
----
-icon: lucide/file-plus
----
-
-# Hooking Up a New Skill
-
-Use this checklist to add a new skill in the docs-first model.
-
-For the full contract details, see [Content Contract](./content.md), [Frontmatter Contract](./frontmatter.md), and [URI Contract](./uris.md).
-
-## Canonical Skill Shape
-
-Create one skill directory under `docs/skills/`:
-
-```text
-docs/
-  skills/
-    <skill-id>/
-      SKILL.md
-      references/
-        ... (optional markdown files, nested folders allowed)
-```
-
-Rules:
-
-1. `SKILL.md` is required.
-2. All skill-specific supporting docs live under `references/`.
-3. Skill directories are ownership boundaries; no cross-skill writes.
-4. `skill-id` is lowercase kebab-case and should remain stable.
-
-## SKILL.md Frontmatter
-
-`SKILL.md` frontmatter is authoritative for metadata.
-
-Required top-level fields:
-
-1. `name`
-2. `description`
-3. `x-personal-mcp`
-
-Required `x-personal-mcp` fields:
-
-1. `id`
-2. `version`
-3. `capabilities`
-
-Optional `x-personal-mcp` fields:
-
-1. `tags`
-2. `depends_on`
-3. `references`
-
-Canonical frontmatter template:
-
-```yaml
----
-name: <skill-id>
-description: <what this skill does and when to use it>
-
-x-personal-mcp:
-  id: <skill-id>
-  version: 1.0.0
-  tags: []
-  capabilities:
-    - resource://skills/<skill-id>/document
-  depends_on: []
-  # Optional: only for nested references or metadata overrides.
-  references:
-    <ref-id>:
-      path: references/<file>.md
-      mime_type: text/markdown
-      title: <optional short title>
----
-```
-
-Reference manifest rules:
-
-1. `ref-id` is lowercase kebab-case.
-2. `path` is skill-relative and must stay under `references/`.
-3. Top-level `references/*.md` files are auto-discovered, and `ref-id` is derived from a normalized filename stem.
-4. Nested `references/**` markdown files must be declared explicitly.
-5. Reference paths are markdown files.
-
-No `metadata.yaml` sidecar is part of this model.
-
-## URI Surface
-
-Canonical resource URIs for a skill:
-
-1. `resource://skills/<skill_id>/document`
-2. `resource://skills/<skill_id>/references/<ref_id>`
-
-Canonical discovery URIs:
-
-1. `resource://catalog/skills_index`
-2. `resource://catalog/skills/{skill_id}`
-
-Docs passthrough URI:
-
-1. `resource://docs/{path*}`
-
-Compatibility rule:
-
-1. Keep URI families unversioned by default.
-2. For breaking changes, update clients to the canonical replacement URIs directly.
-
-## Checklist
-
-1. Create `docs/skills/<skill-id>/SKILL.md`.
-2. Add optional references under `docs/skills/<skill-id>/references/`.
-3. Populate frontmatter with `name`, `description`, and `x-personal-mcp` metadata.
-4. Ensure `x-personal-mcp.id` equals `name` and directory `<skill-id>`.
-5. Ensure `capabilities` includes `resource://skills/<skill-id>/document`.
-6. Add supporting docs under `references/`; top-level markdown files are exposed automatically.
-7. Declare `x-personal-mcp.references` only for nested paths or to override defaults.
-
-## Quick Validation
-
-1. Confirm docs build succeeds:
-
-```bash
-uv run zensical build
-```
-
-2. Confirm tests succeed:
-
-```bash
-uv run pytest -q
-```

docs/skills/new-skill/SKILL.md

@@ -36,7 +36,100 @@ Use this skill to bootstrap a new skill in the docs-first architecture. Try to u
   - [docs/frontmatter.md](../../frontmatter.md)
   - [docs/mcp_layout.md](../../mcp_layout.md)
   - [docs/uris.md](../../uris.md)
-  - [docs/new_skill.md](../../new_skill.md)
+
+## Canonical Skill Shape
+
+Create one skill directory under `docs/skills/`:
+
+```text
+docs/
+  skills/
+    <skill-id>/
+      SKILL.md
+      references/
+        ... (optional markdown files, nested folders allowed)
+```
+
+Rules:
+
+1. `SKILL.md` is required.
+2. All skill-specific supporting docs live under `references/`.
+3. Skill directories are ownership boundaries; no cross-skill writes.
+4. `skill-id` is lowercase kebab-case and should remain stable.
+
+### Framing
+
+Phrasing and language in the skills should reflect the intent of providing preferences and reference documentation, rather than being for a migration or transition. When a particular resource is brought in, it should focus the general way something is done.
+
+## SKILL.md Frontmatter Contract
+
+`SKILL.md` frontmatter is authoritative for skill metadata.
+
+Required top-level fields:
+
+1. `name`
+2. `description`
+3. `x-personal-mcp`
+
+Required `x-personal-mcp` fields:
+
+1. `id`
+2. `version`
+3. `capabilities`
+
+Optional `x-personal-mcp` fields:
+
+1. `tags`
+2. `depends_on`
+3. `references`
+
+Canonical frontmatter template:
+
+```yaml
+---
+name: <skill-id>
+description: <what this skill does and when to use it>
+
+x-personal-mcp:
+  id: <skill-id>
+  version: 1.0.0
+  tags: []
+  capabilities:
+    - resource://skills/<skill-id>/document
+  depends_on: []
+  # Optional: only for nested references or metadata overrides.
+  references:
+    <ref-id>:
+      path: references/<file>.md
+      mime_type: text/markdown
+      title: <optional short title>
+---
+```
+
+Reference manifest rules:
+
+1. `ref-id` is lowercase kebab-case.
+2. `path` is skill-relative and must stay under `references/`.
+3. Top-level `references/*.md` files are auto-discovered, and `ref-id` is derived from a normalized filename stem.
+4. Nested `references/**` markdown files must be declared explicitly.
+5. Reference paths are markdown files.
+
+## URI Surface
+
+Canonical resource URIs for a skill:
+
+1. `resource://skills/<skill_id>/document`
+2. `resource://skills/<skill_id>/references/<ref_id>`
+
+Canonical discovery URIs:
+
+1. `resource://catalog/skills_index`
+2. `resource://catalog/skills/{skill_id}`
+
+Compatibility rule:
+
+1. Keep URI families unversioned by default.
+2. For breaking changes, update clients to the canonical replacement URIs directly.
 
 ## Scope
 

docs/skills/vscode-configuration/SKILL.md

@@ -22,12 +22,20 @@ x-personal-mcp:
 
 Use this skill to design or repair repeatable VS Code workspace configuration for local development workflows.
 
+Primary VS Code source docs:
+
+- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging)
+- [Debug configuration (`launch.json`)](https://code.visualstudio.com/docs/debugtest/debugging-configuration)
+- [Tasks (`tasks.json`)](https://code.visualstudio.com/docs/editor/tasks)
+- [MCP servers in VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
+
 ## 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 `.vscode/mcp.json` workspace or user profile MCP server configuration.
 - You need consistent workspace onboarding where users can run and debug from VS Code with minimal manual setup.
 
 ## Progressive References
@@ -37,6 +45,7 @@ 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)
+- MCP server setup in VS Code: [mcp.json MCP server configuration](./references/mcp-server-configuration.md)
 
 ## Procedure
 

docs/skills/vscode-configuration/references/debug-launch-configurations.md

@@ -1,6 +1,6 @@
 # Debug Launch Configurations in VS Code
 
-This reference focuses on Python debugging through `debugpy` using `.vscode/launch.json`.
+This reference focuses on Python debugging through [`debugpy`](https://github.com/microsoft/debugpy) using [`.vscode/launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration).
 
 ## Core Structure
 
@@ -15,15 +15,15 @@ A minimal launch file:
 
 Useful fields for Python configs:
 
-- `type`: Use `debugpy`.
+- `type`: Use [`debugpy`](https://code.visualstudio.com/docs/python/debugging).
 - `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.
+- `cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)).
-- `env` / `envFile`: Environment variables.
+- `env` / `envFile`: Environment variables (commonly from [environment variable definitions files](https://code.visualstudio.com/docs/python/environments#_environment-variable-definitions-file)).
-- `console`: `integratedTerminal` is usually most practical.
+- `console`: `integratedTerminal` is usually most practical ([launch options](https://code.visualstudio.com/docs/debugtest/debugging-configuration#_launchjson-attributes)).
 - `justMyCode`: `true` by default; set `false` when stepping into dependencies.
 
 ## Launch vs Attach
@@ -46,7 +46,7 @@ Attach profile example:
 }
 ```
 
-Remote process side command example:
+Remote process side command example (from [debugpy CLI usage](https://code.visualstudio.com/docs/python/debugging#_command-line-debugging)):
 
 ```bash
 python -m debugpy --listen 5678 -m your_package.main
@@ -90,6 +90,13 @@ Prefer module mode when imports depend on package layout.
 - Keep secrets out of committed launch configs.
 - Ensure the selected VS Code interpreter matches project tooling.
 
+## Source Documentation
+
+- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging)
+- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration)
+- [Variables reference](https://code.visualstudio.com/docs/editor/variables-reference)
+- [debugpy project](https://github.com/microsoft/debugpy)
+
 ## Troubleshooting
 
 If breakpoints do not hit:

docs/skills/vscode-configuration/references/fastapi-debugpy-launch.md

@@ -1,6 +1,6 @@
 # FastAPI Debug Launch with debugpy
 
-This reference provides practical `.vscode/launch.json` patterns for FastAPI applications started with uvicorn.
+This reference provides practical [`.vscode/launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration) patterns for [FastAPI](https://fastapi.tiangolo.com/) applications started with [uvicorn](https://www.uvicorn.org/).
 
 ## Launch FastAPI via Module
 
@@ -57,9 +57,11 @@ If app is created via factory function:
 }
 ```
 
+Factory mode is powered by uvicorn's [`--factory`](https://www.uvicorn.org/settings/#application) option.
+
 ## Attach to an Existing FastAPI Process
 
-If the app is launched externally, start with debugpy:
+If the app is launched externally, start with [`debugpy`](https://code.visualstudio.com/docs/python/debugging#_command-line-debugging):
 
 ```bash
 python -m debugpy --listen 5678 -m uvicorn your_package.main:app --host 127.0.0.1 --port 8000 --reload
@@ -96,3 +98,10 @@ A profile is considered valid when:
 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.
+
+## Source Documentation
+
+- [FastAPI docs](https://fastapi.tiangolo.com/)
+- [Uvicorn settings and CLI options](https://www.uvicorn.org/settings/)
+- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging)
+- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration)

docs/skills/vscode-configuration/references/mcp-server-configuration.md

@@ -0,0 +1,123 @@
+# Configure MCP Servers in VS Code
+
+Use this reference to configure MCP servers for GitHub Copilot chat in VS Code with `.vscode/mcp.json` (workspace) or profile-level `mcp.json` (user scope).
+
+## Where Configuration Lives
+
+VS Code supports two MCP configuration locations:
+
+- Workspace scope: `.vscode/mcp.json` in the repository.
+- User profile scope: open with the `MCP: Open User Configuration` command.
+
+Use workspace scope for shared team configuration, and user scope for personal or machine-specific servers.
+
+## Minimal mcp.json
+
+```json
+{
+  "servers": {
+    "github": {
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp"
+    },
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@microsoft/mcp-server-playwright"]
+    }
+  }
+}
+```
+
+The `servers` object keys are logical server names shown in VS Code MCP management surfaces.
+
+## Add Servers Through VS Code UI
+
+1. Run `MCP: Add Server` from the Command Palette.
+2. Choose Workspace or Global target.
+3. Review generated config in `mcp.json`.
+4. Start or restart the server from `MCP: List Servers`.
+
+This guided flow is usually safer than manual edits when onboarding teammates.
+
+## Security and Secrets
+
+1. Do not hardcode tokens or API keys in `mcp.json`.
+2. Prefer input variables or environment-file patterns supported by the MCP configuration schema.
+3. Start only trusted servers, because local servers can execute code on your machine.
+4. Use trust prompts as a checkpoint instead of bypassing review.
+
+## Security Best Practices
+
+1. Apply least privilege by default.
+2. Keep workspace `mcp.json` limited to team-safe, non-secret configuration.
+3. Keep personal credentials and machine-specific settings in user-scope configuration, not repository files.
+4. Prefer explicit allowlists for filesystem writes and outbound network access when sandboxing is enabled.
+5. Use one server per trust boundary instead of one large multi-purpose server.
+6. Review server `command` and `args` as code during pull requests.
+7. Disable or uninstall unused MCP servers to reduce attack surface.
+8. Use HTTPS endpoints for remote MCP servers whenever available.
+9. Pin server packages or versions where practical to avoid accidental supply-chain drift.
+10. Reset trust and re-review configuration after major server changes.
+
+### Operational Guardrails
+
+1. Treat MCP resources as publishable unless an explicit access control layer exists.
+2. Capture server logs during onboarding so failures and suspicious behavior are easier to detect.
+3. Define ownership for each server entry, including who approves changes and who rotates secrets.
+4. Document upgrade triggers: if a server starts reading private data or executing side-effectful actions, require stronger access controls before rollout.
+
+### Team Review Checklist
+
+Use this checklist before merging workspace MCP configuration changes:
+
+1. No plaintext secrets in `mcp.json`.
+2. `command` and `args` are from trusted publishers and expected binaries.
+3. Server scope is correct (workspace vs user profile).
+4. Sandboxing is enabled for local `stdio` servers when supported.
+5. Sandbox allowlists are narrow (minimum paths and domains).
+6. The change includes an owner and rollback path.
+
+## Sandbox Local stdio Servers (Linux/macOS)
+
+For local `stdio` servers, enable sandboxing when possible:
+
+```json
+{
+  "servers": {
+    "myServer": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@example/mcp-server"],
+      "sandboxEnabled": true
+    }
+  },
+  "sandbox": {
+    "filesystem": {
+      "allowWrite": ["${workspaceFolder}"]
+    },
+    "network": {
+      "allowedDomains": ["api.example.com"]
+    }
+  }
+}
+```
+
+Sandboxing is currently available on Linux and macOS, not Windows.
+
+## Troubleshooting Checklist
+
+1. Open server logs from `MCP: List Servers` -> `Show Output`.
+2. Confirm trust state (or run `MCP: Reset Trust` if needed).
+3. Confirm server command and arguments run outside VS Code.
+4. Confirm workspace-vs-user scope matches where you expect the server to run.
+5. If using remote development, configure the server in the remote scope when needed.
+
+## Source Documentation
+
+- [Add and manage MCP servers in VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
+- [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
+- [Input variables for sensitive data](https://code.visualstudio.com/docs/agents/reference/mcp-configuration#_input-variables-for-sensitive-data)
+- [Sandbox configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration#_sandbox-configuration)
+- [AI security guidance in VS Code](https://code.visualstudio.com/docs/agents/security)
+- [Model Context Protocol overview](https://modelcontextprotocol.io/docs/getting-started/intro)

docs/skills/vscode-configuration/references/tasks-json-configuration.md

@@ -1,6 +1,6 @@
 # Configure Project Tasks in tasks.json
 
-Use `.vscode/tasks.json` to define repeatable project commands and optional hooks for debugging.
+Use [`.vscode/tasks.json`](https://code.visualstudio.com/docs/editor/tasks) to define repeatable project commands and optional hooks for debugging.
 
 ## Minimal File
 
@@ -14,12 +14,12 @@ Use `.vscode/tasks.json` to define repeatable project commands and optional hook
 ## Task Fields You Will Use Most
 
 - `label`: Task name shown in VS Code.
-- `type`: Usually `shell`.
+- `type`: Usually [`shell`](https://code.visualstudio.com/docs/editor/tasks#_custom-tasks).
 - `command`: Executable to run.
 - `args`: Command arguments.
-- `options.cwd`: Working directory.
+- `options.cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)).
-- `group`: Mark default build or test tasks.
+- `group`: Mark default build or test tasks ([task groups](https://code.visualstudio.com/docs/editor/tasks#_grouping-tasks)).
-- `problemMatcher`: Parse errors into the Problems panel.
+- `problemMatcher`: Parse errors into the Problems panel ([problem matchers](https://code.visualstudio.com/docs/editor/tasks#_defining-a-problem-matcher)).
 - `isBackground`: `true` for long-running tasks (for example dev server watch).
 
 ## Python Project Example
@@ -56,7 +56,7 @@ Use `.vscode/tasks.json` to define repeatable project commands and optional hook
 
 ## Connect Tasks to Debug Profiles
 
-In `launch.json`, you can run a task first:
+In [`launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration), you can run a task first with [`preLaunchTask`](https://code.visualstudio.com/docs/debugtest/debugging-configuration#_launchjson-attributes):
 
 ```json
 {
@@ -90,3 +90,10 @@ If a task fails unexpectedly:
 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.
+
+## Source Documentation
+
+- [VS Code Tasks (official)](https://code.visualstudio.com/docs/editor/tasks)
+- [Tasks Appendix (schema and interfaces)](https://code.visualstudio.com/docs/reference/tasks-appendix)
+- [Variables Reference](https://code.visualstudio.com/docs/editor/variables-reference)
+- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration)