---
icon: lucide/file-text
---

# Content Contract

This page defines the authored content contract for the docs-first MCP architecture.

## Canonical Source Of Truth

1. All authored Markdown lives under `docs/`.
2. MCP resources and static docs are two distribution surfaces of the same authored files.
3. No parallel authored markdown is allowed in `src/` or other package-only paths.

## Canonical Skill Shape

Each skill is one directory under `docs/skills/`:

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

## File Placement And Ownership Boundaries

1. Top-level project docs stay in `docs/*.md`.
2. Skill docs stay in `docs/skills/<skill-id>/...`.
3. A skill may link to other skills, but must not store content inside another skill's directory.
4. Server and runtime code may index and serve docs, but must not be the source of authored markdown.

## 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, including reference id to relative path mappings, is declared from `SKILL.md` frontmatter rather than inferred as a hidden global convention.

## 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`

## Invariants

This contract guarantees:

1. One authored source tree in `docs/` for both website and MCP.
2. One skill directory maps to one skill identity per revision.
3. Namespace and slug drift is minimized by keeping directory and frontmatter ids aligned per revision.
4. Per-skill reference structure can evolve without changing cross-skill architecture.
5. Packaging for stdio is deterministic because authored content is path-stable.

## Non-Goals

This contract does not define:

1. URI versioning policy details.
2. The full frontmatter schema.
3. Migration instructions from the current architecture.