201 lines
6.5 KiB
Markdown
201 lines
6.5 KiB
Markdown
---
|
|
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
|
|
```
|
|
|
|
## 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).
|
|
|
|
## 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. |