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

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

```text
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:

```yaml
---
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

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