prompts/docs/authoring.md

icon

icon
lucide/pencil

Authoring Guide

This page defines the practical workflow for maintaining skills, prompts, and project documentation while keeping root docs/ as the only authored source.

Primary references:

1. Skill Contract
2. Prompt Contract
3. Frontmatter Contract
4. URI Contract
5. Zensical documentation skill

Source Tree Ownership

Edit content only under root docs/. The src/personal_mcp/docs path is a relative symlink for editable installs; do not author through a copied package tree.

Hatchling's normal package traversal follows src/personal_mcp/docs during wheel builds and archives the linked targets as regular files under personal_mcp/docs/. Do not add a force-include entry for root docs/; it duplicates those wheel paths. The installed package therefore gives SkillsDirectoryProvider a regular filesystem directory while Zensical builds the human site directly from root docs/.

Generated site/ content is a build artifact and must not be edited by hand.

Content Layout

docs/
    *.md
    contracts/
    prompts/<prompt-id>/
        PROMPT.md
        references/
    skills/<skill-name>/
        SKILL.md
        references/

Keep skill and prompt files inside their owning directories. Relative links may cross sections, but content ownership should remain clear.

Skill Authoring

A skill is discovered when a direct child of docs/skills/ contains SKILL.md.

Required frontmatter:

---
name: <skill-name>
description: <what the skill does and when to use it>
---

Rules:

1. Use lowercase kebab-case for the directory and name.
2. Keep name exactly equal to the directory name.
3. Write a specific description because clients use it for discovery.
4. Do not add x-personal-mcp, versions, tags, capabilities, or reference mappings.
5. Put supporting material anywhere beneath the skill directory, normally under references/.
6. Link supporting files from SKILL.md so humans and agents understand when to load them.

FastMCP recursively scans every skill file and generates skill://<name>/_manifest. Supporting-resource identity is the real relative path, not a synthetic reference id.

Recommended sequence:

1. Draft or revise SKILL.md routing guidance.
2. Add focused supporting files.
3. Verify relative links.
4. Run the provider tests and docs build.
5. Restart running servers because production uses reload=False.

Prompt Authoring

Prompts pair typed Python metadata with canonical Markdown prose:

1. Add one @prompt function under src/personal_mcp/prompts/components/.
2. Use the function signature for arguments, requiredness, and literal constraints.
3. Set name, description, tags, and version on the decorator.
4. Keep the canonical body in docs/prompts/<prompt-id>/PROMPT.md.
5. Keep Markdown placeholders exactly equal to the Python argument names.
6. Use only documentation-site fields in Markdown frontmatter.

The production FileSystemProvider discovers component modules. Do not add prompt registry models, catalog resources, or dynamic signature generation.

Frontmatter Safety

1. Quote scalar values containing :.
2. Quote values with reserved YAML characters such as #, {}, [], or leading *.
3. Use block scalars for punctuation-heavy multiline text.
4. Keep fields within the applicable skill or documentation contract.

Writing Quality

1. Prefer focused sections and descriptive headings.
2. Link feature-level claims to authoritative sources.
3. Use relative links for internal pages.
4. Keep code examples minimal and actionable.
5. Avoid bare URLs in prose.
6. Load only supporting material relevant to the immediate task.

Copilot Routing

Active instructions should point directly to native main resources:

1. skill://zensical-docs/SKILL.md
2. skill://pytesting/SKILL.md
3. skill://vscode-configuration/SKILL.md

When deeper guidance is needed, read the selected skill's _manifest and fetch supporting files by their listed path.

Validation Checklist

uv run pytest tests/skills/test_provider.py tests/web/test_mcp_skills.py -q
uv run zensical build
uv run ruff check .
uv run ty check
uv run pytest

For packaging changes, also build and inspect an installed wheel so provider path resolution is verified outside the editable checkout.

Navigation

When adding or moving pages:

1. update zensical.toml
2. keep top-level page icons in frontmatter
3. rebuild the site
4. verify internal links and navigation labels