swapped docs symlink
This commit is contained in:
John Lancaster
@@ -0,0 +1,131 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user