consolidated new-skill resource
This commit is contained in:
John Lancaster
@@ -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
|
|
||||||
```
|
|
||||||
@@ -36,7 +36,100 @@ Use this skill to bootstrap a new skill in the docs-first architecture. Try to u
|
|||||||
- [docs/frontmatter.md](../../frontmatter.md)
|
- [docs/frontmatter.md](../../frontmatter.md)
|
||||||
- [docs/mcp_layout.md](../../mcp_layout.md)
|
- [docs/mcp_layout.md](../../mcp_layout.md)
|
||||||
- [docs/uris.md](../../uris.md)
|
- [docs/uris.md](../../uris.md)
|
||||||
- [docs/new_skill.md](../../new_skill.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.
|
||||||
|
|
||||||
|
### Framing
|
||||||
|
|
||||||
|
Phrasing and language in the skills should reflect the intent of providing preferences and reference documentation, rather than being for a migration or transition. When a particular resource is brought in, it should focus the general way something is done.
|
||||||
|
|
||||||
|
## SKILL.md Frontmatter Contract
|
||||||
|
|
||||||
|
`SKILL.md` frontmatter is authoritative for skill 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.
|
||||||
|
|
||||||
|
## 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}`
|
||||||
|
|
||||||
|
Compatibility rule:
|
||||||
|
|
||||||
|
1. Keep URI families unversioned by default.
|
||||||
|
2. For breaking changes, update clients to the canonical replacement URIs directly.
|
||||||
|
|
||||||
## Scope
|
## Scope
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user