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

zensical docs skill

Browse Source
This commit is contained in:
John Lancaster
2026-06-19 00:24:08 -05:00
parent 07475f972f
commit 36abea5940
11 changed files with 164 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/new_skill.md
+10 -4
View File
@@ -14,7 +14,9 @@ Use this checklist after generating a new skill under `docs/skills/<slug>/`.
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 `load_skill_document(skill_id=<skill-id>, skill_slug=<slug>)`.
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`.
@@ -23,7 +25,7 @@ Use this checklist after generating a new skill under `docs/skills/<slug>/`.
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`, and the catalog discovers metadata from `src/personal_mcp/skills/*/metadata.yaml` automatically.
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.
@@ -39,8 +41,9 @@ To keep behavior consistent across MCP clients and Copilot session types, follow
### Do
1. Add or update `metadata.yaml` fields (`id`, `description`, `tags`, `capabilities`) so catalog discovery quality stays high.
2. Use catalog resources as the primary discovery surface.
3. Add thin, read-only catalog tools only when client behavior needs a fallback path.
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
@@ -92,11 +95,14 @@ 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: []
```
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`: