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

consolidated new-skill resource

Browse Source
This commit is contained in:
John Lancaster
2026-06-20 18:18:44 -05:00
parent 38edc4ac36
commit 06d5fc18f2
2 changed files with 94 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/new_skill.md
-129
View File
@@ -1,129 +0,0 @@
---
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: []
# 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:
```bash
uv run zensical build
```
2. Confirm tests succeed:
```bash
uv run pytest -q
```