prompts/docs/new_skill.md

icon

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, Frontmatter Contract, and URI Contract.

Canonical Skill Shape

Create one skill directory under docs/skills/:

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:

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

uv run zensical build

2. Confirm tests succeed:

uv run pytest -q