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

Compare commits

base: john/prompts:c73771c2f43e97f7245039ed8e2fb3b767a4a3fd
Branches Tags
john/prompts:main john/prompts:better-restructure
..
compare: john/prompts:06d5fc18f2f780fa73e46ae10cf6f27ba1646bb1
Branches Tags
john/prompts:main john/prompts:better-restructure

2 Commits
c73771c2f4 .. 06d5fc18f2

Author SHA1 Message Date
John Lancaster 06d5fc18f2 consolidated new-skill resource 2026-06-20 18:18:44 -05:00
John Lancaster 38edc4ac36 vscode config improvements 2026-06-20 18:05:05 -05:00
7 changed files with 263 additions and 144 deletions
Expand all files Collapse all files
docs/new_skill.md
-129
View File
@@ -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
+94 -1
View File
@@ -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
+9
View File
@@ -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
+13 -6
View File
@@ -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.
- `env` / `envFile`: Environment variables.
- `console`: `integratedTerminal` is usually most practical.
- `cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)).
- `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 ([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
+11 -2
View File
@@ -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
+123
View File
@@ -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
+13 -6
View File
@@ -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.
- `group`: Mark default build or test tasks.
- `problemMatcher`: Parse errors into the Problems panel.
- `options.cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)).
- `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 ([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)