consolidated new-skill resource

2026-06-20 18:18:44 -05:00
parent 38edc4ac36
commit 06d5fc18f2
2 changed files with 94 additions and 130 deletions
@@ -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-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