prompts/docs/content.md

icon

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

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.