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

## 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. If references are exposed, declare each `ref-id` in `x-personal-mcp.references`.

## Quick Validation

1. Confirm docs build succeeds:

```bash
uv run zensical build
```

2. Confirm tests succeed:

```bash
uv run pytest -q
```