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