132 lines
4.7 KiB
Markdown
132 lines
4.7 KiB
Markdown
---
|
|
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
|
|
|
|
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
|
|
|
|
```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
|