contract updates

2026-06-21 22:29:46 -05:00
parent 123c491413
commit c893173fcc
7 changed files with 181 additions and 46 deletions
@@ -0,0 +1,75 @@
+---
+icon: lucide/brain-circuit
+---
+
+# Skill Contract
+
+This page defines the canonical contract for skills in the docs-first MCP architecture.
+
+## Canonical Skill Shape
+
+Each skill is one directory under `docs/skills/`:
+
+```mermaid
+---
+config:
+		treeView:
+				rowIndent: 20
+				lineThickness: 2
+		themeVariables:
+				treeView:
+						labelColor: '#FFFFFF'
+						lineColor: '#FFFFFF'
+---
+treeView-beta
+	"docs/"
+		"... (other docs)"
+		"skills/"
+			"<skill-id>/"
+				"SKILL.md"
+				"references/"
+					"... (one or more markdown files, optional nested folders)"
+```
+
+Rules:
+
+1. `SKILL.md` is required for every skill.
+2. `references/` is the only place for skill-specific supporting docs.
+3. Nested folders inside `references/` are allowed so a skill can reorganize internals without changing global architecture.
+4. Skill directories are independent ownership boundaries; no cross-skill file writes.
+
+## Metadata Location Constraint
+
+1. Skill metadata is embedded in YAML frontmatter in `SKILL.md`.
+2. No `metadata.yaml` sidecar exists in the end state.
+3. Reference lookup metadata is documented and explicit: top-level `references/*.md` are auto-discovered from filenames, while `SKILL.md` frontmatter declares overrides and nested mappings when needed.
+
+## Skill Id Contract
+
+`skill-id` is the public identifier and should satisfy all rules below:
+
+1. Format: lowercase kebab-case only.
+2. Character set: `a-z`, `0-9`, and `-`.
+3. Must start with a letter.
+4. No underscores, spaces, dots, or uppercase characters.
+5. Directory name should equal `skill-id` in each committed revision.
+6. Frontmatter `id` should equal directory name in each committed revision.
+7. Treat `skill-id` as immutable after release; any rename is a breaking replacement and clients must move to the new id.
+
+Valid examples:
+
+1. `fastapi-uv-docker`
+2. `zensical-docs`
+3. `pytest-scaffolding`
+
+Invalid examples:
+
+1. `fastapi_uv_docker`
+2. `Zensical-Docs`
+3. `docs.zensical`
+
+## Direct Documentation Inclusion
+
+1. For direct API documentation, use mkdocstrings directives rather than pasting large code blocks.
+2. Keep manually-authored code examples short and task-focused; large implementation excerpts are out of scope for this contract.
+