prompts/docs/contracts/skill_contract.md

icon

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/:

---
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 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.