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

implemented steps 1-5

Browse Source
This commit is contained in:
John Lancaster
2026-06-20 14:08:59 -05:00
parent c273ecfc54
commit 19f3c1740a
53 changed files with 1454 additions and 762 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+76 -18
View File
@@ -16,6 +16,12 @@ The system is complete in three layers:
2. Catalog resources provide normalized discovery.
3. Zensical builds a static site from those same Markdown sources and the FastAPI app serves it in the FastMCP runtime process.
For Phase 1, this architecture is anchored by three contracts:
1. Step 1: docs-first authored content contract under `docs/` with strict per-skill ownership.
2. Step 2: SKILL.md frontmatter contract with Anthropic fields plus `x-personal-mcp` metadata.
3. Step 3: canonical resource URI contract with break-and-replace policy for contract changes.
This architecture keeps authored content human-friendly while preserving machine-stable contracts.
## Intent
@@ -30,7 +36,14 @@ The architecture is designed to satisfy three long-term requirements:
### Pattern Modules
Each module encapsulates one methodology domain and publishes resource families:
Each skill encapsulates one methodology domain in a docs-owned directory:
1. `docs/skills/<skill-id>/SKILL.md`
2. `docs/skills/<skill-id>/references/...`
The skill document and references are the authored source of truth; runtime code indexes and serves these files without becoming a second authored source.
Each skill publishes resource families:
1. document
@@ -42,10 +55,23 @@ The catalog is the canonical discovery layer and publishes normalized records fo
Typical catalog resources:
1. resource://catalog/patterns
2. resource://catalog/patterns_by_id
3. resource://catalog/skills_index
4. resource://catalog/skills_details
1. resource://catalog/skills_index
2. resource://catalog/skills/{skill_id}
Only canonical catalog resources are part of the runtime contract in this phase.
### Registry Loader
Phase 2 runtime composition introduces a startup registry loader that reads packaged docs resources using `importlib.resources.files(...)` and `Traversable` APIs.
Loader responsibilities:
1. Parse SKILL.md frontmatter for each skill.
2. Validate schema and cross-field constraints before any resource registration.
3. Build an in-memory registry keyed by `skill_id`.
4. Fail fast for duplicate ids, missing markdown files, broken reference mappings, and invalid `depends_on` values.
Registry load failure is a startup error, not a partial runtime warning.
### Content Sources
@@ -76,27 +102,59 @@ flowchart TD
### Metadata Contract
Each pattern module declares:
Each skill declares frontmatter in `docs/skills/<skill-id>/SKILL.md`.
Anthropic-facing required fields:
1. name
2. description
Repository indexing metadata is declared in `x-personal-mcp`:
1. id
2. name
3. version
4. description
5. tags
6. capabilities
7. depends_on
2. version
3. tags
4. capabilities
5. depends_on
6. references map (ref id to relative path and optional metadata)
No `metadata.yaml` sidecar is part of the end-state contract.
### URI Contract
Module resource URIs are stable and follow:
Canonical resource URIs are:
1. resource://skills/<skill_id>/document
2. resource://skills/<skill_id>/references/<ref_id>
3. resource://catalog/skills_index
4. resource://catalog/skills/{skill_id}
5. resource://docs/{path*}
Catalog resource URIs are stable and discovery-focused.
Validation rules:
1. `skill_id` is lowercase kebab-case and must satisfy the stable skill id contract.
2. `ref_id` is lowercase kebab-case and must be declared in the skill references manifest.
3. `path*` resolves only to normalized markdown paths under `docs/`.
### Resource Registration Contract
Resources are registered from the validated registry, not by ad hoc per-skill hardcoding.
Registration rules:
1. Use RFC6570 URI templates where appropriate.
2. Mark documentation resources as read-only and idempotent.
3. Set explicit mime types for resource responses.
4. Configure duplicate URI handling with `on_duplicate="error"` for startup safety.
This keeps runtime behavior deterministic and prevents accidental URI collisions.
### Versioning Rule
Published URIs are immutable. Behavioral or schema changes are versioned in metadata and documented through additive migration notes.
URIs are unversioned and canonical in this phase.
1. Breaking URI changes are handled as direct replacement.
2. No compatibility aliases or dual URI families are maintained.
## Static Hosting Pattern
@@ -161,8 +219,8 @@ Allowed exception:
Existing markdown reference sets are valid examples of authored source material for this architecture:
1. ../docs/skills/pytest-scaffolding/references/pytest-docs.md
2. ../docs/skills/python-logging-dictconfig/references/python-logging-docs.md
3. ../docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md
1. docs/skills/pytest-scaffolding/references/pytest-docs.md
2. docs/skills/python-logging-dictconfig/references/python-logging-docs.md
3. docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md
These inputs are treated as content sources, while resource URIs and catalog payloads remain the machine-facing contracts.
docs/copilot.md
+6 -4
View File
@@ -18,7 +18,7 @@ Copilot interacts with MCP servers through separate capability lanes:
These lanes are related but independently gated in the client.
The documented reliable paths are:
Reliable paths are:
1. attach MCP resources explicitly through `Add Context > MCP Resources` or `MCP: Browse Resources`
2. let Copilot invoke MCP tools when the task and tool descriptions make that relevant
@@ -57,7 +57,7 @@ Use this sequence to confirm behavior:
## Recommended Usage Pattern
1. rely on catalog resources for discovery (`skills_index`, `patterns`, etc.)
1. rely on canonical catalog resources for discovery (`skills_index`, then `skills/{skill_id}`)
2. fetch only selected skill documents for context
3. keep slash commands for deterministic fallback flows
@@ -134,8 +134,10 @@ When a task may benefit from personal-mcp skills, use this sequence:
Preferred discovery order:
1. `resource://catalog/skills_index` or `resource://catalog/patterns`
2. `resource://skills/<skill-id>/document`
1. `resource://catalog/skills_index`
2. `resource://catalog/skills/{skill_id}`
3. `resource://skills/<skill-id>/document`
4. `resource://skills/<skill-id>/references/<ref-id>` when needed
Tool fallback order:
docs/index.md
+2 -2
View File
@@ -4,11 +4,11 @@ icon: lucide/rocket
# Personal MCP
This is a document library of software patterns, best practices, and structured references to external documentation, which are available in 2, equivalent ways. The same, exact markdown files are reused for both cases, so there is never any incongruity between them.
This project is a document library of software patterns, best practices, and structured references to external documentation. The same markdown files are published through two equivalent surfaces, so human-readable docs and MCP resources stay aligned.
## MCP Server
An [MCP server](https://modelcontextprotocol.io/docs/getting-started/intro) at `/mcp` to provide context for AI systems. The markdown files are exposed as [resources](https://modelcontextprotocol.io/docs/learn/server-concepts#resources) and are structured to be easily consumed by [MCP clients](https://modelcontextprotocol.io/docs/learn/client-concepts), like VSCode.
An [MCP server](https://modelcontextprotocol.io/docs/getting-started/intro) at `/mcp` provides context for AI systems. The markdown files are exposed as [resources](https://modelcontextprotocol.io/docs/learn/server-concepts#resources) and are structured to be easily consumed by [MCP clients](https://modelcontextprotocol.io/docs/learn/client-concepts), such as VS Code.
## Docs
docs/mcp_contract_steps_1_5.md
+66
View File
@@ -0,0 +1,66 @@
# FastMCP Greenfield Contracts (Steps 1-5)
## Step 1: End-State Content Contract
1. All authored markdown lives under docs/.
2. Skill docs live under docs/skills/<skill-id>/.
3. Canonical skill shape is:
```text
docs/
skills/
<skill-id>/
SKILL.md
references/
```
4. SKILL.md is required for every skill.
5. references/ is the only place for skill-specific supporting docs.
6. Skill directories are ownership boundaries.
7. Skill id rules:
- lowercase kebab-case
- starts with a letter
- directory name matches skill id
- SKILL frontmatter id matches directory name
## Step 2: SKILL Frontmatter and Metadata Contract
1. name and description are required top-level frontmatter fields.
2. Repository indexing metadata lives in x-personal-mcp.
3. x-personal-mcp fields:
- required: id, version, capabilities
- optional: tags, depends_on, references
4. references maps stable ref ids to skill-relative markdown paths under references/.
5. metadata.yaml sidecars are not part of the canonical model.
## Step 3: URI Contract and Compatibility Policy
Canonical URI surface:
1. resource://catalog/skills_index
2. resource://catalog/skills/{skill_id}
3. resource://skills/{skill_id}/document
4. resource://skills/{skill_id}/references/{ref_id}
5. resource://docs/{path*}
Rules:
1. skill_id and ref_id are lowercase kebab-case.
2. docs path is markdown-only and cannot traverse outside docs/.
3. URI families are unversioned and canonical in this phase.
4. Breaking changes use direct replacement with no compatibility aliases.
## Step 4: Docs Registry Loader Contract
1. Loader uses importlib.resources.files(...) and Traversable APIs.
2. Startup validates SKILL frontmatter schema, id invariants, reference integrity, dependency graph, and URI uniqueness.
3. Registry is immutable for request-time reads.
4. Invalid docs state is a hard startup error.
## Step 5: Registry-Driven Resource Registration Contract
1. FastMCP resources are registered from the validated registry.
2. RFC6570 templates are used for parameterized routes.
3. Docs resources declare explicit MIME types.
4. Docs resources include readOnlyHint and idempotentHint annotations.
5. Duplicate registrations fail startup via strict duplicate policy.
docs/mcp_layout.md
+64 -15
View File
@@ -30,14 +30,36 @@ treeView-beta
"index.md"
"architecture.md"
"mcp_layout.md"
"mcp_contract_steps_1_5.md"
"skills"
"new-skill"
"SKILL.md"
"references"
"copilot-customization"
"SKILL.md"
"references"
"fastapi-async-sqlalchemy-modernization"
"SKILL.md"
"references"
"fastapi-uv-docker"
"SKILL.md"
"references"
"nicegui"
"SKILL.md"
"references"
"nicegui-ui-customization"
"SKILL.md"
"references"
"pytest-scaffolding"
"SKILL.md"
"references"
"python-logging-dictconfig"
"SKILL.md"
"references"
"fastapi-uv-docker"
"vscode-configuration"
"SKILL.md"
"references"
"zensical-docs"
"SKILL.md"
"references"
"site"
@@ -45,15 +67,14 @@ treeView-beta
"src"
"personal_mcp"
"main.py"
"mcp.py"
"web"
"app.py"
"docs_mount.py"
"catalog"
"server.py"
"skills"
"pytest_scaffolding"
"python_logging_dictconfig"
"fastapi_uv_docker"
"document_loader.py"
```
Notes:
@@ -72,12 +93,21 @@ The runtime process serves two surfaces:
```mermaid
flowchart TD
A[FastMCP Root Server] --> B[MCP Transport]
A --> C[FastAPI Application]
C --> D[Static Mount /docs]
D --> E[Zensical site output directory]
A[Docs Registry Loader] --> B[Validated In-Memory Registry]
B --> C[FastMCP Resource Registration]
C --> D[MCP Transport]
C --> E[FastAPI Application]
E --> F[Static Mount /docs]
F --> G[Zensical site output directory]
```
Runtime guarantees:
1. Docs registry load and validation happen before resource exposure.
2. Duplicate resource and template registration fails startup (`on_duplicate="error"`).
3. Resource registration is metadata-driven from SKILL frontmatter and reference manifests.
4. Legacy per-skill Python servers and `metadata.yaml` sidecars are not part of the runtime.
## Build and Publish Flow
The docs flow is pre-build only.
@@ -103,12 +133,31 @@ MCP resources map directly to canonical Markdown documents.
Example mapping model:
1. docs/skills/<slug>/SKILL.md -> resource://skills/<id>/document
2. docs/skills/<slug>/references/*.md -> referenced sections or linked companion documents
1. docs/skills/<skill-id>/SKILL.md -> resource://skills/<skill_id>/document
2. docs/skills/<skill-id>/references/<file>.md -> resource://skills/<skill_id>/references/<ref_id> (via frontmatter references manifest)
3. docs/<path>.md -> resource://docs/{path*}
Catalog resources provide discovery metadata and stable identifiers.
Catalog discovery resources are:
When clients cannot attach MCP resources directly, catalog-level tools may retrieve the same underlying skill documents indirectly. This does not create a second content source; it is only an alternate access path to the same markdown-backed contract.
1. resource://catalog/skills_index
2. resource://catalog/skills/{skill_id}
Registry-backed registration details:
1. `resource://skills/{skill_id}/document` resolves to each skill's SKILL.md.
2. `resource://skills/{skill_id}/references/{ref_id}` resolves through frontmatter reference manifests.
3. `resource://docs/{path*}` resolves normalized markdown paths under `docs/`.
4. Resource metadata includes explicit mime type and read-only/idempotent annotations.
When clients cannot attach MCP resources directly, thin catalog tools may retrieve the same underlying skill documents indirectly. This does not create a second content source.
## URI Compatibility Policy
This phase is a greenfield break-and-replace baseline.
1. Canonical URIs are the only supported URIs in this runtime.
2. No backward-compatibility aliases or dual registration paths are maintained.
3. Contract changes should update clients to canonical URIs directly.
## Why This Pattern
@@ -155,8 +204,8 @@ This keeps docs publication explicit and predictable.
Existing reference docs remain valid content inputs in this pattern:
1. ../docs/skills/pytest-scaffolding/references/pytest-docs.md
2. ../docs/skills/python-logging-dictconfig/references/python-logging-docs.md
3. ../docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md
1. docs/skills/pytest-scaffolding/references/pytest-docs.md
2. docs/skills/python-logging-dictconfig/references/python-logging-docs.md
3. docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md
These are source documents, not deployment artifacts.
docs/new_skill.md
+106 -165
View File
@@ -1,178 +1,119 @@
# Hooking Up a New Skill
Use this checklist after generating a new skill under `docs/skills/<slug>/`.
Use this checklist to add a new skill in the Phase 1 docs-first model.
## Step 1 Contract: 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.
## Step 2 Contract: 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: []
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. Reference paths are markdown files.
No `metadata.yaml` sidecar is part of this model.
## Step 3 Contract: 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 the authored docs content.
Add `docs/skills/<slug>/SKILL.md` and any companion files under `docs/skills/<slug>/references/`.
2. Choose the three names up front.
Use a docs slug like `fastapi-uv-docker`, a resource id like `fastapi-uv-docker`, and a Python package name like `fastapi_uv_docker`.
3. Add the runtime package.
Create `src/personal_mcp/skills/<python_namespace>/` with `__init__.py`, `server.py`, and `metadata.yaml`.
4. Expose the document resource in `server.py`.
Follow the existing pattern: create a `FastMCP` instance, register `resource://skills/<skill-id>/document`, and return the shared loader result.
For the default layout, load `docs/skills/<slug>/SKILL.md`.
For special cases, set `document_path` in `metadata.yaml` to a repo-relative Markdown file and load from metadata instead of hardcoding a path in the server.
5. Register the catalog metadata.
In `metadata.yaml`, add the skill `id`, `name`, `version`, `description`, `tags`, `capabilities`, and `depends_on`. The `capabilities` list should include `resource://skills/<skill-id>/document`.
6. Mount the skill in the root server.
Import the new server in `src/personal_mcp/mcp.py` and add an `mcp.mount(...)` call with the Python namespace.
7. Let the loader and catalog do the rest.
The document loader reads canonical Markdown from `docs/skills/<slug>/SKILL.md` by default, or from `metadata.yaml`'s optional `document_path` override when present. The catalog discovers metadata from `src/personal_mcp/skills/*/metadata.yaml` automatically.
8. Rebuild and smoke-test.
Run `uv run zensical build` to publish the docs site, then run a quick Python check or start the app to confirm the new resource loads.
## Discovery Tool Policy
To keep behavior consistent across MCP clients and Copilot session types, follow this boundary:
1. Keep per-skill servers resource-only.
2. Keep discovery/query tools centralized in the catalog server.
3. Keep canonical content in `docs/skills/<slug>/SKILL.md` and expose it through `resource://skills/<skill-id>/document`.
### Do
1. Add or update `metadata.yaml` fields (`id`, `description`, `tags`, `capabilities`) so catalog discovery quality stays high.
2. Use `document_path` when a skill should expose a Markdown file outside `docs/skills/<slug>/SKILL.md`.
3. Use catalog resources as the primary discovery surface.
4. Add thin, read-only catalog tools only when client behavior needs a fallback path.
### Don't
1. Do not add duplicate discovery tools to each skill package.
2. Do not duplicate canonical skill guidance in tool descriptions.
3. Do not create mutating catalog tools for skill discovery.
## Minimal Shape
- Docs content: `docs/skills/<slug>/SKILL.md`
- Optional references: `docs/skills/<slug>/references/*.md`
- Runtime package: `src/personal_mcp/skills/<python_namespace>/`
- Resource URI: `resource://skills/<skill-id>/document`
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. If references are exposed, declare each `ref-id` in `x-personal-mcp.references`.
## Quick Validation
1. Confirm the Markdown document resolves through the loader.
`uv run python -c "from personal_mcp.skills.document_loader import load_skill_document; print(load_skill_document(skill_id='<skill-id>', skill_slug='<slug>')['source_path'])"`
1. Confirm docs build succeeds:
2. Confirm the docs build still works.
`uv run zensical build`
## server.py Template
```python
from fastmcp import FastMCP
from personal_mcp.skills.document_loader import load_skill_document
<python_namespace>_server = FastMCP("<skill-id>")
@<python_namespace>_server.resource("resource://skills/<skill-id>/document")
def skill_document() -> dict[str, str]:
"""Return the canonical Markdown document for this skill."""
return load_skill_document(
skill_id="<skill-id>",
skill_slug="<slug>",
)
```bash
uv run zensical build
```
## metadata.yaml Template
2. Confirm tests succeed:
```yaml
id: <skill-id>
name: <Human Readable Name>
version: 1.0.0
description: <One sentence describing what the skill provides.>
tags:
- <tag-one>
- <tag-two>
document_path: <optional repo-relative path to a markdown file>
capabilities:
- resource://skills/<skill-id>/document
depends_on: []
```bash
uv run pytest -q
```
Omit `document_path` when the canonical document is `docs/skills/<slug>/SKILL.md`.
## Root Mount Template
Add an import in `src/personal_mcp/mcp.py`:
```python
from personal_mcp.skills.<python_namespace>.server import <python_namespace>_server
```
Add a mount call:
```python
mcp.mount(<python_namespace>_server, namespace="<python_namespace>")
```
## Example Scaffold
For a new skill called `sqlmodel-patterns`:
1. Docs content lives in `docs/skills/sqlmodel-patterns/SKILL.md`.
2. The Python package lives in `src/personal_mcp/skills/sqlmodel_patterns/`.
3. The resource id is `sqlmodel-patterns`.
Example `server.py`:
```python
from fastmcp import FastMCP
from personal_mcp.skills.document_loader import load_skill_document
sqlmodel_patterns_server = FastMCP("sqlmodel-patterns")
@sqlmodel_patterns_server.resource("resource://skills/sqlmodel-patterns/document")
def skill_document() -> dict[str, str]:
"""Return the canonical Markdown document for this skill."""
return load_skill_document(
skill_id="sqlmodel-patterns",
skill_slug="sqlmodel-patterns",
)
```
Example `metadata.yaml`:
```yaml
id: sqlmodel-patterns
name: SQLModel Patterns
version: 1.0.0
description: Provide reusable patterns for building apps with SQLModel.
tags:
- sqlmodel
- python
- patterns
capabilities:
- resource://skills/sqlmodel-patterns/document
depends_on: []
```
Example `mcp.py` additions:
```python
from personal_mcp.skills.sqlmodel_patterns.server import sqlmodel_patterns_server
mcp.mount(sqlmodel_patterns_server, namespace="sqlmodel_patterns")
```
## Bootstrap Sequence
1. Create `docs/skills/<slug>/SKILL.md`.
2. Copy the `server.py` template into `src/personal_mcp/skills/<python_namespace>/server.py`.
3. Copy the `metadata.yaml` template into `src/personal_mcp/skills/<python_namespace>/metadata.yaml`.
4. Add `__init__.py` in the new package directory.
5. Import and mount the server in `src/personal_mcp/mcp.py`.
6. Run the validation commands above.
docs/skills/copilot-customization/SKILL.md
+32 -8
View File
@@ -2,6 +2,31 @@
name: copilot-customization
description: 'Plan, create, review, and debug GitHub Copilot and VS Code agent customizations, including instructions, prompt files, skills, custom agents, hooks, MCP servers, and repo-specific personal-mcp skill integration.'
argument-hint: 'What Copilot behavior are you customizing, and should it be workspace-scoped, personal, or exposed as an MCP skill resource?'
x-personal-mcp:
id: copilot-customization
version: 1.0.0
tags:
- copilot
- vscode
- customization
- instructions
- prompts
- agent-skills
- custom-agents
- hooks
- mcp
- personal-mcp
- skills
capabilities:
- resource://skills/copilot-customization/document
depends_on:
- new-skill
- zensical-docs
references:
vscode-customization:
path: references/vscode-customization.md
mime_type: text/markdown
title: VS Code Customization
---
# Copilot Customization
@@ -51,15 +76,14 @@ Use [VS Code customization references](./references/vscode-customization.md) for
When adding a new skill to this `personal-mcp` repo, follow the resource-first pattern:
1. Search the catalog for `new skill` and load `resource://skills/new-skill/document`.
2. Create authored docs under `docs/skills/<slug>/SKILL.md`, with optional one-level `references/` files.
3. Choose consistent names: docs slug and resource id use kebab-case; Python namespace uses snake_case.
4. Create `src/personal_mcp/skills/<python_namespace>/` with `__init__.py`, `server.py`, and `metadata.yaml`.
5. Expose only `resource://skills/<skill-id>/document` from the per-skill server.
6. Put discovery metadata in `metadata.yaml`, including `id`, `name`, `version`, `description`, `tags`, `capabilities`, and `depends_on`.
7. Mount the skill server in `src/personal_mcp/mcp.py` using the Python namespace.
8. Validate with the document loader and `uv run zensical build`.
2. Create authored docs under `docs/skills/<skill-id>/SKILL.md`, with optional nested `references/` markdown files.
3. Keep `skill-id` stable and consistent across directory name, `name`, and `x-personal-mcp.id`.
4. Put discovery metadata in `SKILL.md` frontmatter under `x-personal-mcp`.
5. Declare `resource://skills/<skill-id>/document` in `x-personal-mcp.capabilities`.
6. Declare references in `x-personal-mcp.references` as `ref-id -> references/<file>.md` mappings.
7. Validate with the registry loader and `uv run zensical build`.
Keep per-skill servers resource-only. Catalog-level discovery is the only place for thin fallback discovery tools.
Keep runtime implementation registry-driven in `src/personal_mcp/mcp.py`; do not add per-skill Python server modules.
## Quality Checks
docs/skills/fastapi-async-sqlalchemy-modernization/SKILL.md
+40
View File
@@ -2,6 +2,46 @@
name: fastapi-async-sqlalchemy-modernization
description: 'Create a step-by-step modernization plan for an existing FastAPI app using SQLAlchemy async patterns, context managers, and AsyncExitStack. Use when: planning migration from legacy DB setup, standardizing async engine/session lifecycles, defining transaction boundaries, and aligning with SQLAlchemy 2.x best practices.'
argument-hint: 'What is your current FastAPI + SQLAlchemy setup (sync/async driver, session pattern, lifespan usage, and deployment model)?'
x-personal-mcp:
id: fastapi-async-sqlalchemy-modernization
version: 1.0.0
tags:
- fastapi
- sqlalchemy
- async
- modernization
capabilities:
- resource://skills/fastapi-async-sqlalchemy-modernization/document
depends_on: []
references:
index:
path: references/index.md
mime_type: text/markdown
title: Index
engine:
path: references/engine.md
mime_type: text/markdown
title: Engine
session:
path: references/session.md
mime_type: text/markdown
title: Session
transactions:
path: references/transactions.md
mime_type: text/markdown
title: Transactions
implicit-io:
path: references/implicit_io.md
mime_type: text/markdown
title: Implicit IO
observability:
path: references/observability.md
mime_type: text/markdown
title: Observability
template:
path: references/template.md
mime_type: text/markdown
title: Template
---
# FastAPI Async SQLAlchemy Modernization Plan
docs/skills/fastapi-uv-docker/SKILL.md
+27
View File
@@ -2,6 +2,33 @@
name: fastapi-uv-docker
description: 'Audit and migrate an existing Python project to best practices for a cloud-native ASGI FastAPI app managed with uv and run with uvicorn in Docker. Use when: conforming a project to production standards, setting up src layout, configuring pyproject.toml, writing multi-stage Dockerfiles, wiring lifespan and settings, adding health endpoints, enforcing non-root container user, migrating from requirements.txt to uv.'
argument-hint: 'What is the current state of the project (bare Python, requirements.txt, pip, etc.)?'
x-personal-mcp:
id: fastapi-uv-docker
version: 1.0.0
tags:
- fastapi
- uv
- docker
capabilities:
- resource://skills/fastapi-uv-docker/document
depends_on: []
references:
fastapi-best-practices:
path: references/fastapi-best-practices.md
mime_type: text/markdown
title: FastAPI Best Practices
uv-project-layout:
path: references/uv-project-layout.md
mime_type: text/markdown
title: uv Project Layout
uvicorn-settings:
path: references/uvicorn-settings.md
mime_type: text/markdown
title: Uvicorn Settings
docker-cloud-native:
path: references/docker-cloud-native.md
mime_type: text/markdown
title: Docker Cloud Native
---
# FastAPI Project Best Practices
docs/skills/new-skill/SKILL.md
+42
View File
@@ -0,0 +1,42 @@
---
name: new-skill
description: Provide a practical checklist and baseline template for creating a new docs-first MCP skill in this repository.
argument-hint: What skill are you creating, and what problem should it solve?
x-personal-mcp:
id: new-skill
version: 1.0.0
tags:
- fastmcp
- bootstrap
- scaffolding
- skills
- mcp
capabilities:
- resource://skills/new-skill/document
depends_on: []
references: {}
---
# New Skill Bootstrap
Use this skill to bootstrap a new skill in the docs-first architecture.
## Scope
1. Create docs under docs/skills/<skill-id>/.
2. Define SKILL frontmatter with Anthropic and x-personal-mcp fields.
3. Declare references via x-personal-mcp.references when needed.
4. Validate the docs build and MCP resource reads.
## Authoring Checklist
1. Create docs/skills/<skill-id>/SKILL.md.
2. Add docs/skills/<skill-id>/references/ files as needed.
3. Keep skill id and directory name aligned.
4. Keep frontmatter name equal to x-personal-mcp.id.
5. Include resource://skills/<skill-id>/document in capabilities.
## Validation
1. uv run zensical build
2. uv run pytest -q
docs/skills/nicegui-ui-customization/SKILL.md
+24
View File
@@ -2,6 +2,30 @@
name: nicegui-ui-customization
description: 'Design and implement production NiceGUI UIs with reusable components, Tailwind-first styling, event-driven interactions, and troubleshooting for uploads, state, and static assets. Use when building or refactoring NiceGUI pages and interaction flows.'
argument-hint: 'What UI outcome should this workflow produce?'
x-personal-mcp:
id: nicegui-ui-customization
version: 1.0.0
tags:
- nicegui
- ui
- customization
- frontend
capabilities:
- resource://skills/nicegui-ui-customization/document
depends_on: []
references:
architecture-and-styling:
path: references/architecture-and-styling.md
mime_type: text/markdown
title: Architecture and Styling
interaction-patterns:
path: references/interaction-patterns.md
mime_type: text/markdown
title: Interaction Patterns
troubleshooting-and-quality-gates:
path: references/troubleshooting-and-quality-gates.md
mime_type: text/markdown
title: Troubleshooting and Quality Gates
---
# NiceGUI UI Customization Workflow
docs/skills/nicegui/SKILL.md
+20
View File
@@ -2,6 +2,26 @@
name: nicegui
description: 'Design and scaffold a production-ready NiceGUI + FastAPI application architecture. Use for multi-page app planning, package boundaries, optional DB/LangGraph/docs integration, and implementation checklists.'
argument-hint: 'What should this app include (pages, DB, AI, docs, constraints)?'
x-personal-mcp:
id: nicegui
version: 1.0.0
tags:
- nicegui
- fastapi
- ui
- architecture
capabilities:
- resource://skills/nicegui/document
depends_on: []
references:
architecture:
path: references/architecture.md
mime_type: text/markdown
title: Architecture
source-documentation:
path: references/source-documentation.md
mime_type: text/markdown
title: Source Documentation
---
# NiceGUI
docs/skills/pytest-scaffolding/SKILL.md
+23
View File
@@ -2,6 +2,29 @@
name: pytest-scaffolding
description: "Scaffold a maintainable, hierarchical pytest suite with fast defaults and clear escalation paths for FastAPI and SQLAlchemy tests. Use when creating or reorganizing tests, defining fixture/marker boundaries, or making test strategy progressively discoverable."
argument-hint: "Target scope plus stack details (pure Python, FastAPI, SQLAlchemy sync, SQLAlchemy async, or mixed)"
x-personal-mcp:
id: pytest-scaffolding
version: 1.0.0
tags:
- pytest
- testing
- python
capabilities:
- resource://skills/pytest-scaffolding/document
depends_on: []
references:
pytest-docs:
path: references/pytest-docs.md
mime_type: text/markdown
title: Pytest Docs
fastapi-testing:
path: references/fastapi-testing.md
mime_type: text/markdown
title: FastAPI Testing
sqlalchemy-testing:
path: references/sqlalchemy-testing.md
mime_type: text/markdown
title: SQLAlchemy Testing
---
# Pytest Scaffolding
docs/skills/python-logging-dictconfig/SKILL.md
+15
View File
@@ -2,6 +2,21 @@
name: python-logging-dictconfig
description: 'Set up idiomatic Python logging with logging.config.dictConfig. Use when creating or refactoring logging setup, standardizing handlers/formatters, and enforcing centralized config.'
argument-hint: 'Target context (single script, package, FastAPI app, or CLI) and desired log destinations'
x-personal-mcp:
id: python-logging-dictconfig
version: 1.0.0
tags:
- logging
- python
- observability
capabilities:
- resource://skills/python-logging-dictconfig/document
depends_on: []
references:
python-logging-docs:
path: references/python-logging-docs.md
mime_type: text/markdown
title: Python Logging Docs
---
# Idiomatic Python Logging with dictConfig
docs/skills/vscode-configuration/SKILL.md
+27
View File
@@ -2,6 +2,33 @@
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
docs/skills/zensical-docs/SKILL.md
+43
View File
@@ -2,6 +2,49 @@
name: zensical-docs
description: 'Reference skill for Zensical documentation mechanics. Use for quick lookup of docs structure, feature options, and source links, then edit this skill over time to record project preferences for when each feature should be used.'
argument-hint: 'What are you documenting, who is the audience, and what Zensical features are in scope?'
x-personal-mcp:
id: zensical-docs
version: 1.0.0
tags:
- zensical
- mkdocs
- mkdocs-material
- mkdocstrings
- docs
- documentation
- information-architecture
- skills
- bootstrap
- discovery
- authoring
capabilities:
- resource://skills/zensical-docs/document
depends_on: []
references:
index:
path: references/index.md
mime_type: text/markdown
title: Source Map
zensical-features:
path: references/zensical-features.md
mime_type: text/markdown
title: Feature Catalog
theme-customization-and-icons:
path: references/theme-customization-and-icons.md
mime_type: text/markdown
title: Theme Customization and Icons
documentation-quality:
path: references/documentation-quality.md
mime_type: text/markdown
title: Documentation Quality
discoverability-and-ia:
path: references/discoverability-and-ia.md
mime_type: text/markdown
title: Discoverability and IA
code-heavy-docs-and-mkdocstrings:
path: references/code-heavy-docs-and-mkdocstrings.md
mime_type: text/markdown
title: Code-Heavy Docs and Mkdocstrings
---
# Zensical Documentation Authoring
docs/usage.md
+9 -8
View File
@@ -9,7 +9,7 @@ icon: lucide/workflow
This page explains practical usage mechanics for the GitHub Copilot extension in VS Code when `personal-mcp` is configured as an MCP server:
1. explicit `/` command flows when you want deterministic control
2. automatic skill context loading when relevance can be inferred
2. guided skill loading when relevance can be inferred
The goal is to show how Copilot behaves as a client and how to shape that behavior.
@@ -26,18 +26,17 @@ In this repository, skill guidance is exposed as MCP resources, not as server-ow
### What the server publishes
`personal-mcp` mounts skill modules and a catalog module. The catalog exposes discovery resources:
`personal-mcp` registers resources from the validated docs registry and exposes catalog discovery resources:
1. `resource://catalog/skills_index`
2. `resource://catalog/skills_details`
3. `resource://catalog/patterns`
4. `resource://catalog/patterns_by_id`
2. `resource://catalog/skills/{skill_id}`
Each skill publishes a canonical Markdown document resource:
1. `resource://skills/<skill-id>/document`
2. `resource://skills/<skill-id>/references/<ref-id>`
The document payload is loaded from `docs/skills/<slug>/SKILL.md` and returned with metadata.
The document payload is loaded from `docs/skills/<skill-id>/SKILL.md` and returned with metadata.
### What Copilot does as the client
@@ -177,8 +176,10 @@ When a task may match a documented implementation pattern from `personal-mcp`:
Preferred resource order:
1. `resource://catalog/skills_index` or `resource://catalog/patterns`
2. `resource://skills/<skill-id>/document`
1. `resource://catalog/skills_index`
2. `resource://catalog/skills/{skill_id}`
3. `resource://skills/<skill-id>/document`
4. `resource://skills/<skill-id>/references/<ref-id>` when needed
Preferred tool fallback order: