---
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](./contracts/skill_contract.md)
- [Prompt contract](./contracts/prompt.md)
- [Frontmatter contract](./contracts/frontmatter.md)
- [URI contract](./contracts/uris.md)
- [Zensical documentation authoring skill](./skills/zensical-docs/SKILL.md)

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

```text
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](./contracts/frontmatter.md) and [Skill contract](./contracts/skill_contract.md).

## 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](./contracts/prompt.md).

## 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](https://modelcontextprotocol.io/docs/getting-started/intro)
- [FastMCP docs](https://gofastmcp.com/getting-started/welcome)
- [Zensical docs](https://zensical.org/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:

```yaml
---
icon: lucide/pencil
---
```

## Validation Checklist

Run these checks before considering authoring changes complete:

```bash
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.