John Lancaster
88 lines
2.9 KiB
Markdown
88 lines
2.9 KiB
Markdown
---
|
|
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. |