prompts/docs/authoring.md

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

## Source Tree Ownership

Edit content only under the repository root `docs/` directory. The `src/personal_mcp/docs` path is a relative symlink provided so package-oriented tooling and editable installs see the same files; do not replace it with copied content or author files through a second tree.

[Hatchling forced inclusion](https://hatch.pypa.io/latest/config/build/#forced-inclusion) projects root `docs/` into `personal_mcp/docs/` when building the wheel. Installed code reads that destination through [`importlib.resources`](https://docs.python.org/3/library/importlib.resources.html), while Zensical continues to build the human-facing site directly from root `docs/`.

Package import does not load these resources. A runnable MCP or FastAPI server loads and validates them when its factory runs, then caches the immutable registry for that process. Restart initialized development or worker processes after changing authored Markdown.

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

## Prompt Argument Mechanics

When defining prompt inputs, keep argument metadata aligned with the prompt contract and runtime behavior.

1. Define arguments under `x-personal-mcp.arguments` as a map keyed by argument name.
2. Argument names must match Python identifier format: `^[A-Za-z_][A-Za-z0-9_]*$`.
3. Each argument entry supports only:
	 - `title` (optional)
	 - `description` (optional)
	 - `required` (optional, defaults to `false`)
4. Unknown argument fields are rejected by strict frontmatter validation.
5. Prompt argument metadata appears in `resource://catalog/prompts/{prompt_id}`, and MCP prompt objects expose the same arguments for prompt-list/get-prompt workflows.
6. Enum-like constraints are not a native argument field; encode allowed values in `description`.

### Frontmatter Safety Rules

Use these rules to avoid YAML parse failures in prompt and skill frontmatter:

1. Quote any scalar value that contains `:` (for example, `description: "Enum: skill | prompt | shim"`).
2. Prefer quoted scalars for values with reserved YAML characters such as `#`, `{}`, `[]`, or leading `*`.
3. If a description needs multiple lines, use a block scalar (`|`) instead of packing punctuation-heavy text into one line.
4. Keep frontmatter keys simple and contract-bound; do not add undeclared argument fields.

### Validation Timing

Run validation immediately after frontmatter edits, not only at the end of a task:

1. First pass after metadata changes: `uv run zensical build`
2. Prompt/skill load verification: `uv run pytest -q`
3. Final full pass before completion: run the full checklist in [Validation Checklist](#validation-checklist)

Example:

```yaml
x-personal-mcp:
	arguments:
		artifact_type:
			title: Artifact type
			description: Allowed values are skill, prompt, or shim.
			required: true
		scope_glob:
			title: Scope glob
			description: Optional applyTo glob for shim outputs.
			required: false
```

References:

1. [Frontmatter contract](./contracts/frontmatter.md)
2. [URI contract](./contracts/uris.md)
3. [Resource-First Pattern Module Architecture](./architecture.md)
4. [Prompt objects concept docs](https://modelcontextprotocol.io/docs/learn/server-concepts#prompts)

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

## Authoring for GitHub Copilot

For resource selection or tool-based matching to work well, each skill should have:

1. precise `description`
2. focused `tags`
3. explicit `capabilities`
4. stable `id` and slug naming

Weak metadata reduces Copilot match quality and increases wrong context injection.

### Copilot Instruction Authoring Pattern

If you want Copilot to use `personal-mcp` skill content more reliably, instruction files should describe three things clearly:

1. when MCP-backed skill guidance is relevant
2. which retrieval path Copilot should prefer first
3. how much skill context it should load before answering

Instructions strongly steer discovery behavior, but they do not force VS Code to auto-attach MCP resources. Keep wording explicit about preferred path and fallback path.

Repository policy:

1. start from catalog discovery
2. prefer MCP resources when the current chat surface exposes resource attachment
3. fall back to catalog tools when resource attachment is unavailable
4. keep loaded skill context bounded

Suggested instruction text:

```md
When a task may match a documented implementation pattern from `personal-mcp`:

1. Start with catalog-first discovery.
2. Prefer MCP resources when the chat surface exposes resource attachment.
3. If MCP resource attachment is unavailable, use `list_resources`/`read_resource` first, then thin catalog tools if needed.
4. Load only the most relevant skill document, or at most 2 skill documents.
5. Reconcile loaded skill guidance with the actual repository code before making changes.

Preferred resource order:

1. `resource://catalog/skills_index`
2. `resource://catalog/skills/{skill_id}`
3. `resource://skills/<skill-id>/document`
4. `resource://skills/<skill-id>/references/<ref-id>` when needed

Preferred tool fallback order:

1. `list_resources`
2. `read_resource`
3. `search_patterns`
4. `get_pattern_by_id`
5. `get_skill_document_by_id`

Compatibility aliases for clients that use `catalog_*` naming are also available:

1. `catalog_search_patterns`
2. `catalog_get_pattern_by_id`
3. `catalog_get_skill_document_by_id`
4. `catalog_search_prompts`
5. `catalog_get_prompt_by_id`

Use canonical names first; aliases exist only to preserve interoperability when a client emits non-canonical names.

If confidence is low after discovery, ask one clarifying question before loading more context.
```

This is guidance, not a guarantee. It defines a reliable policy while preserving the resource-first architecture.

Thin shim path binding guidance for MCP consumers is covered in [Skill Usage Mechanics](./usage.md).

## Zensical Details

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

Address any errors or warnings that result.

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.