Docs manager
Use when writing or reviewing pynchy documentation, deciding where to document things, updating the docs, checking doc consistency, or fixing broken links. Covers information architecture, writing philosophy, tree-shaped navigation, doc-code coupling, no hard-coded usernames, extensibility framing for pluggable subsystems, and when to add code comments.From its SKILL.md
npx -y skills add crypdick/pynchy --skill docs-managerAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 10 stars10 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
- runs commandsInstructs the agent to run 1 command, including `uv run mkdocs build --strict`.
SKILL.md
3.1 KB, 622 tokens by cl100k_base, as published. Nobody here has run it
Documentation Manager
Helps decide where to document things and maintain consistency across Pynchy docs.
Style Guide
- Write for a user trying to achieve a goal. Don't chronicle the evolution of the codebase. Don't go into unnecessary technical details that are not relevant to the user's goal.
- Follow the Google Style Guide. Write in the present tense. Don't use "we" or "they". Write in the active voice. Don't use "is" or "are".
- Read
docs/contributing/contributing-docs.mdfor the full documentation philosophy and information architecture rules.
Where to Document What
Quick decision tree:
New feature?
- Architecture decision →
docs/architecture/(find the relevant topic file, or create a new one) - Installation requirement →
docs/install.md - Security implication →
docs/architecture/security.md - Development workflow change →
.claude/skills/pynchy-dev/SKILL.md
Bug fix?
- If it needs install change →
docs/install.md - Usually: No doc update needed
Refactoring?
- If user-visible → Update relevant docs
- If internal only → No doc update
File Purposes
| File | What Goes There |
|---|---|
README.md | Philosophy, quick start, high-level overview |
docs/install.md | Complete installation guide |
docs/architecture/security.md | Security model, threat analysis |
docs/architecture/index.md | Architecture overview and links to topic pages |
docs/architecture/*.md | One topic per file (containers, routing, tasks, etc.) |
.claude/skills/ | Development context skills for Claude Code agents |
Information Architecture Rules
- Single source of truth — Every concept explained in exactly one place. Cross-link, don't duplicate.
- Tree-shaped navigation — Root files have links + short summaries. Leaf files have the actual content.
- Small, focused files — One topic per file. If it covers multiple concerns, split it.
Validation
Before committing:
# Check for broken links
uv run mkdocs build --strict
After moving/renaming files:
- Search for all references to old name
- Update each reference
- Update
mkdocs.ymlnav - Test with
uv run mkdocs build --strict
Common Mistakes
- Duplicating content across files (link instead)
- Chronological explanations ("First we tried X...")
- Mixing audiences (keep README brief, details in docs/)
- Forgetting to update references after renames
- Writing mega-files that cover multiple topics
Link Checking
Link validation runs automatically in prek hooks. If docs have broken links, the commit will fail.
To manually check: uv run mkdocs build --strict
What ships with it
Read from the repository
Just SKILL.md. No reference files, no scripts.