prompts/docs/authoring.md

icon

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
• Prompt contract
• Frontmatter contract
• URI contract
• Zensical documentation authoring skill

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:

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 and Skill contract.

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.

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
• FastMCP docs
• Zensical 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:

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.

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:

---
icon: lucide/pencil
---

Validation Checklist

Run these checks before considering authoring changes complete:

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.