diff --git a/docs/new_skill.md b/docs/new_skill.md deleted file mode 100644 index eac848e..0000000 --- a/docs/new_skill.md +++ /dev/null @@ -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.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: -description: - -x-personal-mcp: - id: - version: 1.0.0 - tags: [] - capabilities: - - resource://skills//document - depends_on: [] - # Optional: only for nested references or metadata overrides. - references: - : - path: references/.md - mime_type: text/markdown - 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//document` -2. `resource://skills//references/` - -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.md`. -2. Add optional references under `docs/skills//references/`. -3. Populate frontmatter with `name`, `description`, and `x-personal-mcp` metadata. -4. Ensure `x-personal-mcp.id` equals `name` and directory ``. -5. Ensure `capabilities` includes `resource://skills//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 -``` diff --git a/docs/skills/new-skill/SKILL.md b/docs/skills/new-skill/SKILL.md index d65dfe2..fc87ef9 100644 --- a/docs/skills/new-skill/SKILL.md +++ b/docs/skills/new-skill/SKILL.md @@ -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/mcp_layout.md](../../mcp_layout.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.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: +description: + +x-personal-mcp: + id: + version: 1.0.0 + tags: [] + capabilities: + - resource://skills//document + depends_on: [] + # Optional: only for nested references or metadata overrides. + references: + : + path: references/.md + mime_type: text/markdown + 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//document` +2. `resource://skills//references/` + +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