prompts/.github/prompts/plan-step1.prompt.md

Step 1 Results: End-State Content Contract

This section finalizes Step 1 by defining the canonical authored content model.

Step Deliverable

• Update the current docs/ directory with the finalized Step 1 content contract from this document.

Canonical source of truth

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

Canonical skill shape (Anthropic-compatible)

Each skill is one directory under docs/skills/:

docs/
	skills/
		<skill-id>/
			SKILL.md
			references/
				... (one or more markdown files, optional nested folders)

Rules:

• SKILL.md is required for every skill.
• references/ is the only place for skill-specific supporting docs.
• Nested folders inside references/ are allowed so a skill can reorganize internals without changing global architecture.
• Skill directories are independent ownership boundaries; no cross-skill file writes.

File placement and ownership boundaries

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

Metadata location constraint

• Skill metadata is embedded in YAML frontmatter in SKILL.md.
• No metadata.yaml sidecar in the end state.
• Reference lookup metadata (ids to relative paths) is declared from SKILL.md frontmatter, not inferred as a hidden global convention.

Skill-id contract (change-friendly)

skill-id is the public identifier and SHOULD satisfy all rules below:

• Format: lowercase kebab-case only.
• Character set: a-z, 0-9, and -.
• Must start with a letter.
• No underscores, spaces, dots, or uppercase characters.
• Directory name should equal skill-id in each committed revision.
• Frontmatter id should equal directory name in each committed revision.
• Treat skill-id as immutable after release; any rename is a breaking replacement and clients must move to the new id.

Example valid ids:

• fastapi-uv-docker
• zensical-docs
• pytest-scaffolding

Example invalid ids:

• fastapi_uv_docker (underscore)
• Zensical-Docs (uppercase)
• docs.zensical (dot)

Invariants this contract guarantees

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

Non-goals for Step 1

• No URI versioning policy details yet (handled in Step 3).
• No full frontmatter schema details yet (handled in Step 2).
• No migration instructions from current architecture (out of scope for this plan).