Hooking Up a New Skill

Use this checklist after generating a new skill under docs/skills/<slug>/.

Checklist

Create the authored docs content. Add docs/skills/<slug>/SKILL.md and any companion files under docs/skills/<slug>/references/.
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.
Add the runtime package. Create src/personal_mcp/skills/<python_namespace>/ with __init__.py, server.py, and metadata.yaml.
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.
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.
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.
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.
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:

Keep per-skill servers resource-only.
Keep discovery/query tools centralized in the catalog server.
Keep canonical content in docs/skills/<slug>/SKILL.md and expose it through resource://skills/<skill-id>/document.

Do

Add or update metadata.yaml fields (id, description, tags, capabilities) so catalog discovery quality stays high.
Use document_path when a skill should expose a Markdown file outside docs/skills/<slug>/SKILL.md.
Use catalog resources as the primary discovery surface.
Add thin, read-only catalog tools only when client behavior needs a fallback path.

Don't

Do not add duplicate discovery tools to each skill package.
Do not duplicate canonical skill guidance in tool descriptions.
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

Quick Validation

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'])"
Confirm the docs build still works. uv run zensical build

server.py Template

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>",
    )

metadata.yaml Template

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: []

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:

from personal_mcp.skills.<python_namespace>.server import <python_namespace>_server

Add a mount call:

mcp.mount(<python_namespace>_server, namespace="<python_namespace>")

Example Scaffold

For a new skill called sqlmodel-patterns:

Docs content lives in docs/skills/sqlmodel-patterns/SKILL.md.
The Python package lives in src/personal_mcp/skills/sqlmodel_patterns/.
The resource id is sqlmodel-patterns.

Example server.py:

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:

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:

from personal_mcp.skills.sqlmodel_patterns.server import sqlmodel_patterns_server

mcp.mount(sqlmodel_patterns_server, namespace="sqlmodel_patterns")

Bootstrap Sequence

Create docs/skills/<slug>/SKILL.md.
Copy the server.py template into src/personal_mcp/skills/<python_namespace>/server.py.
Copy the metadata.yaml template into src/personal_mcp/skills/<python_namespace>/metadata.yaml.
Add __init__.py in the new package directory.
Import and mount the server in src/personal_mcp/mcp.py.
Run the validation commands above.

6.0 KiB Raw Permalink Blame History