prompts/docs/skills/zensical-docs/SKILL.md

name, description, argument-hint, x-personal-mcp

name	description	argument-hint	x-personal-mcp
zensical-docs	Reference skill for Zensical documentation mechanics. Use for quick lookup of docs structure, feature options, and source links. Prefer inline Markdown links to source docs and avoid bare URLs because this content is rendered as human docs and MCP resources.	What are you documenting, who is the audience, and what Zensical features are in scope?	id version tags capabilities depends_on zensical-docs 1.0.0 zensical mkdocs mkdocs-material mkdocstrings docs documentation information-architecture skills bootstrap discovery authoring resource://skills/zensical-docs/document

Zensical Documentation Authoring

Use this as a compact reference for Zensical mechanics and as the place to record evolving preferences for how this repository uses them.

When to Use

• You need a quick reminder of Zensical features, docs structure, or configuration mechanics.
• You want direct links back to source documentation before changing docs behavior.
• You want one small file you can keep editing as your preferences around docs authoring become clearer.

How To Use This Skill

1. Start here for a quick decision about what kind of docs change you are making.
2. Open only the linked reference that matches the current task.
3. Add or revise preference notes in this file when you decide how this repo should use a feature.

Quick Reference Map

Open only what you need:

• Official docs and source map: source map
• Zensical feature catalog and setup links: feature catalog
• Theme, icons, and visual customization: theme customization
• Writing quality and review criteria: documentation quality
• Navigation and discoverability patterns: discoverability and IA
• Code-heavy docs and API reference patterns: code-heavy docs

Common Cases

New docs project

• Start with uv run zensical new.
• Then review the source map and feature catalog.

Restructuring docs or navigation

• Review discoverability and IA.
• Use it to decide overview pages, section structure, and cross-linking.

Improving writing quality

• Review documentation quality.
• Use it for page quality gates, trust signals, and review criteria.

Adjusting theme or UI mechanics

• Review theme customization.
• Use it for icons, color, theme extensions, and presentation choices.

Documenting APIs or code-heavy systems

• Review code-heavy docs.
• Use it when generated API reference belongs alongside hand-authored docs.

Preferences To Maintain Here

Keep this section short and revise it over time.

Preferred feature choices

• Add the Zensical features you usually enable first.
• Note which features are situational and why.
• Prefer Zensical-native features and conventions when they cover the need cleanly.
• Expect general backward compatibility with MkDocs patterns and configuration unless there is a documented reason not to.

Preferred docs structure

• Record whether this repo prefers explicit nav, index pages, task-first docs, or another pattern.

Preferred API docs approach

• Record whether to use mkdocstrings, how much API surface to publish, and how to link task docs back to reference pages.

Source-First Rule

When making a recommendation, link back to the relevant reference file first, and when possible to the upstream docs linked from that reference.

Link Formatting Rule

Because this project publishes the same markdown for both /docs and MCP resources, link quality is part of the content contract.

• Never leave a bare URL in prose or list items.
• Prefer using in-place Markdown links with meaningful labels.
• For external sources, prefer [descriptive label](https://...) over raw https://....
• For internal files, prefer relative Markdown links so rendered docs remain navigable.
• Any mention of a library or a specific library feature should include a link to source documentation somewhere on the page.
• If inline linking is awkward or the citation payload is too large, use a footnote or tooltip citation instead.

Example preferred style:

• See [importlib.resources](https://docs.python.org/3/library/importlib.resources.html) for packaging details.

Example to avoid:

• See https://docs.python.org/3/library/importlib.resources.html for packaging details.

Acceptable alternatives when inline links are not ideal:

• Add a footnote-style source citation at the end of the section or page.
• Add a tooltip citation when the docs pattern supports it.

Compatibility Rule

Prefer the Zensical-native way of doing something when it exists and is well-supported. Assume MkDocs compatibility is still expected for most configuration and authoring patterns, and call out any case where a Zensical recommendation intentionally diverges from standard MkDocs behavior.

Output Contract

Return only what is useful for the current docs task:

1. Which reference to read next.
2. The smallest recommended docs or config change.
3. Any repo-specific preference this suggests should be added back into this skill.
4. For any library or feature-level claim, include a source-doc citation somewhere (inline link preferred; footnote or tooltip acceptable).