swapped docs symlink

2026-08-07 21:07:23 -05:00
parent 5005cd7001
commit f240486a7e
92 changed files with 69 additions and 42 deletions
@@ -0,0 +1,85 @@
+---
+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.md` frontmatter contains only standard `name` and `description` fields.
+2. No `metadata.yaml` sidecar or repository-specific skill metadata block exists.
+3. The provider discovers supporting files recursively; their real relative paths are published in the generated `_manifest`.
+
+## 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 equals `skill-id` in each committed revision.
+6. Frontmatter `name` equals the directory name.
+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. `pytesting`
+
+Invalid examples:
+
+1. `fastapi_uv_docker`
+2. `Zensical-Docs`
+3. `docs.zensical`
+
+## Provider Publication
+
+[`SkillsDirectoryProvider`](https://gofastmcp.com/servers/providers/skills) scans `docs/skills/` with `supporting_files="template"` and publishes:
+
+1. `skill://<skill-id>/SKILL.md`
+2. `skill://<skill-id>/_manifest`
+3. `skill://<skill-id>/{path*}` for supporting files
+
+Only the main file and manifest appear in `resources/list`. Clients inspect the manifest before reading supporting paths.
+
+## 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.
+