documentation-templates_skill

Overview

This skill provides ready-to-use documentation templates and structure guidelines for project front pages, API docs, code comments, changelogs, architecture decisions, and AI-friendly docs. It helps teams produce clear, scannable, and machine-friendly documentation that speeds onboarding and supports automated agents. Use the templates as starting points and adapt them to your project conventions.

How this skill works

The skill supplies concise templates for common documentation artifacts: a project front page, per-endpoint API docs, JSDoc/TSDoc comment blocks, changelog entries, ADRs, and agent-focused manifests like llms.txt. It emphasizes hierarchical headings, examples-first content, JSON/YAML samples, and practices that make docs both human- and AI-consumable. You can copy templates into your docs folder and follow the structure principles to keep content consistent and up to date.

When to use it

• Creating or updating the project front page and quick start instructions
• Documenting HTTP endpoints with clear parameters, responses, and examples
• Writing JSDoc/TSDoc for public APIs and complex business logic
• Recording architectural decisions using ADRs before or after implementation
• Preparing docs for retrieval-augmented systems or AI crawlers (llms.txt)

Best practices

• Prioritize scannability: use headers, short lists, and tables for key info
• Start with concrete examples and minimal working steps before details
• Document why a decision exists, not just how it was implemented
• Keep changelogs concise and versioned under an Unreleased section
• Provide JSON/YAML examples and mermaid diagrams for RAG and agent indexing

Example use cases

• Front-page template with one-line objective and quick start to reduce onboarding time
• Per-endpoint API pages listing parameters, responses, and request/response examples
• JSDoc/TSDoc blocks for library functions including params, returns, throws, and examples
• ADR template to record trade-offs for major architecture changes
• llms.txt and core-files index to help AI agents locate key code and docs for automated analysis