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