documentation-system_skill

Overview

This skill defines a Documentation System for clear, maintainable docs tuned for both human readers and AI navigation. It prescribes a minimal folder structure, content guidelines, and maintenance workflows so docs stay useful as code evolves. The approach emphasizes progressive disclosure and documenting intent over implementation noise. Use it to decide where docs belong, how to write them, and when to update them after changes.

How this skill works

Documentation lives under a single docs/ root with three top-level areas: system, packages, and guides, each with an index.md for navigation. Writers select a template, place content in the appropriate folder, and follow rules that favor explaining logic and flows rather than repeating code. Maintenance checks map code changes to affected docs and require updating descriptions and references. The system is organized so both humans and AI agents can find and update the right document quickly.

When to use it

• Creating a new document or reorganizing documentation layout.
• Writing or reviewing content to decide scope and style.
• Updating docs after code changes to keep descriptions accurate.
• Choosing whether content belongs in system, packages, or guides.
• Onboarding new contributors to learn where to find key information.

Best practices

• Start with an overview (progressive disclosure) then add details and examples.
• Document intent, system behavior, and flows—avoid restating code or syntax.
• Use templates for consistency and add each doc to its folder index.md.
• Keep docs minimal but complete; exclude auto-generated or highly volatile details.
• Run a quick mapping from changed files to docs after any code change.

Example use cases

• Adding a new package: create docs/packages/[package-name].md from template and link it in packages/index.md.
• Explaining a system flow: put conceptual diagrams and high-level behavior in docs/system/index.md and deep dives in system/*.md.
• Writing a how-to: add a step-by-step guide with examples in docs/guides/ and link to related package docs.
• Post-PR doc check: identify touched modules, verify affected docs, and update any stale descriptions.
• Deciding placement: consult structure reference to choose between system, package, or guide locations.