prompts/docs/contracts/index.md

icon

icon
lucide/file-check-2

Contracts

This section groups the core data and contract documents for the repository.

Pages

1. Prompt Contract
2. Skill Contract
3. Frontmatter Contract
4. URI Contract

Use these pages as the normative source for authored content layout, frontmatter schema, and canonical MCP URI semantics.

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 Content Shape

Authored content is organized under docs/:

---
config:
    treeView:
        rowIndent: 20
        lineThickness: 2
    themeVariables:
        treeView:
            labelColor: '#FFFFFF'
            lineColor: '#FFFFFF'
---
treeView-beta
  "docs/"
    "*.md (top-level docs pages)"
    "contracts/"
      "prompt.md"
      "skill_contract.md"
      "frontmatter.md"
      "uris.md"
    "prompts/"
      "<prompt-id>/"
        "PROMPT.md"
    "skills/"
      "<skill-id>/"
        "SKILL.md"
        "references/..."

File Placement And Ownership Boundaries

1. Top-level project docs stay in docs/*.md.
2. Skill docs stay in docs/skills/<skill-id>/....
3. Prompt docs stay in docs/prompts/<prompt-id>/....
4. A skill or prompt may link across sections, but must not store content in another artifact's directory.
5. Server and runtime code may index and serve docs, but must not be the source of authored markdown.

Delegated Contracts

1. Skill-specific directory, metadata, and id rules are defined in Skill Contract.
2. Prompt-specific directory, metadata, and id rules are defined in Prompt Contract.

Invariants

This contract guarantees:

1. One authored source tree in docs/ for both website and MCP.
2. Skill and prompt artifacts remain path-stable within their own sections.
3. Cross-surface publishing remains deterministic because authored content paths are canonical.

Non-Goals

This contract does not define:

1. URI versioning policy details.
2. The full frontmatter schema.
3. Detailed skill rules (see Skill Contract).
4. Detailed prompt rules (see Prompt Contract).