John Lancaster
122 lines
2.6 KiB
Markdown
122 lines
2.6 KiB
Markdown
# 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
|
|
```
|