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