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

A prompt is one self-describing docs/prompts/<prompt-id>/PROMPT.md file:

1. Create a lowercase kebab-case directory beneath docs/prompts/.
2. Add a nested prompt frontmatter mapping with version, description, tags, and ordered arguments.
3. Give every argument a description and explicit required flag.
4. Add choices only when a string argument accepts a fixed set of values.
5. Use each argument exactly once or more as a {{argument_name}} placeholder in the body.
6. Do not add a Python component, name field, metadata sidecar, or central catalog entry.

The custom provider rescans prompt documents during every native list and get request. Changes in an editable checkout are therefore visible on the next request without a process restart. Invalid metadata or placeholder drift fails that request with a configuration error.

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