prompts/docs/authoring.md

icon

icon
lucide/pencil

Authoring Guide

This page defines the practical authoring workflow for this repository so Markdown remains the single source of truth for both published docs and MCP resources.

Primary references:

• Skill contract
• Prompt contract
• Frontmatter contract
• URI contract
• Zensical documentation authoring skill

What You Author

This repository has two primary authored content types:

1. Skills under docs/skills/<skill-id>/.
2. Prompts under docs/prompts/<prompt-id>/.

Each module keeps one canonical document plus optional references:

docs/
	skills/<skill-id>/
		SKILL.md
		references/
			*.md

	prompts/<prompt-id>/
		PROMPT.md
		references/
			*.md

Authoring Principles

1. Keep Markdown as the canonical source and avoid duplicating content into alternate metadata files.
2. Prefer resource-first discovery paths (resource://catalog/... then resource://skills/... or resource://prompts/...).
3. Keep pages focused and composable: overview in the primary doc, details in references/.
4. Use descriptive inline links for external sources instead of bare URLs.
5. Use stable ids and slugs; renames are breaking changes and should be intentional.

Skill Authoring Workflow

When creating or updating a skill:

1. Confirm slug format is lowercase kebab-case.
2. Keep directory name, name, and x-personal-mcp.id aligned.
3. Ensure capabilities include resource://skills/<skill-id>/document.
4. Place supporting material under references/.
5. Use explicit frontmatter reference entries only when you need overrides or nested mappings.

Recommended sequence:

1. Draft SKILL.md intent and routing sections.
2. Add or refine references/*.md.
3. Verify links and example commands.
4. Run docs build and tests.

For exact metadata rules, see Frontmatter contract and Skill contract.

Prompt Authoring Workflow

When creating or updating a prompt module:

1. Keep one canonical PROMPT.md.
2. Keep name, x-personal-mcp.id, and directory slug aligned.
3. Include resource://prompts/<prompt-id>/document in capabilities.
4. Define prompt arguments in x-personal-mcp.arguments when inputs are required.
5. Keep long rationale and source notes in references/ to preserve prompt clarity.

For exact structure, see Prompt contract.

Writing Quality Rules

Apply these defaults to all docs pages:

1. Prefer short sections with strong headings over long unbroken prose.
2. Keep claims source-linked, especially for MCP, FastMCP, pytest, FastAPI, SQLAlchemy, and Zensical behavior.
3. Prefer relative links for internal docs paths.
4. Use code blocks for commands and configuration snippets.
5. Keep examples minimal and actionable.

Source examples:

• Model Context Protocol docs
• FastMCP docs
• Zensical docs

Navigation And Frontmatter

When adding or restructuring pages:

1. Update navigation in zensical.toml.
2. Ensure top-level pages include frontmatter with an icon.
3. Keep naming and labels concise so navigation remains scannable.

Top-level page pattern:

---
icon: lucide/pencil
---

Validation Checklist

Run these checks before considering authoring changes complete:

uv run zensical build
uv run ruff check .
uv run ty check
uv run pytest

If a change only affects docs content, uv run zensical build is still required.

Quick Authoring Checklist

1. Correct location (skills/ or prompts/).
2. Frontmatter id and slug alignment.
3. Capability URI present.
4. Links valid and descriptive.
5. Navigation updated when needed.
6. Validation commands passed.