documentation-standards

The documentation-standards skill provides a comprehensive framework for managing repository-wide technical information within the PRPM ecosystem. It establishes a clear taxonomy for document placement, separating content into development-specific guides, user-facing tutorials, and specialized knowledge bases for AI agents. By following these standards, contributors and automated systems can locate information predictably, reducing context switching and improving the reliability of AI-assisted coding operations. This skill acts as a structural reference for repository maintenance, documentation versioning, and lifecycle management.

• Categorizes documentation into Internal (development/docs/), User-Facing (docs/), Project-Level (root), and AI-specific (.claude/skills/) directories for intuitive navigation.

• Defines explicit Markdown structure requirements including frontmatter usage, heading hierarchy (H1-H3), table of contents for long-form content, and standardized code-block formatting.

• Provides a migration checklist to ensure link integrity and repository health during document reorganization, including automated checks for broken links using markdown-link-check.

• Mandates package-specific README structures to facilitate API reference, usage tutorials, and CLI command documentation within individual package directories.

• Integrates with automated documentation tools like TypeDoc, VitePress, and Docusaurus to support future static site generation and multi-format output.

• Enforces cross-referencing conventions using relative paths, ensuring that navigation between internal development resources and external user guides remains robust.

• Designed for PRPM contributors, maintainers, package authors, and AI agents operating within the repository.

• Best practices for adding, deprecating, and reviewing documentation to ensure the information remains accurate and relevant as the project evolves.

• Supports automated linting workflows via markdownlint to maintain style consistency and prevent formatting regressions.

• Ideal for managing the complexities of a multi-package repository where technical debt often manifests as disorganized or outdated documentation.

• Encourages regular quarterly reviews and systematic updates to CHANGELOG.md, ensuring that all feature additions and project milestones are properly documented.