documentation-templates
Documentation templates for README, API docs, and code comments.
When & Why to Use This Skill
This Claude skill provides a comprehensive collection of standardized documentation templates and structural guidelines tailored for modern software projects. It includes ready-to-use formats for README files, API documentation, JSDoc/TSDoc comments, Changelogs, and Architecture Decision Records (ADRs). Additionally, it features AI-friendly documentation patterns like llms.txt to optimize codebases for RAG indexing and AI agent interaction, ensuring high maintainability and professional standards.
Use Cases
- 1. Rapid Project Setup: Instantly generate structured README.md files with essential sections like Quick Start, Features, and Configuration for new repositories.
- 2. API Documentation: Standardize endpoint descriptions with clear parameter tables, response codes, and request examples to improve developer experience.
- 3. Code Quality Improvement: Apply JSDoc/TSDoc templates to functions and classes to provide clear business logic explanations and improve IDE auto-completion.
- 4. Architectural Governance: Utilize ADR (Architecture Decision Record) templates to track technical decisions, context, and consequences across the project lifecycle.
- 5. AI-Ready Knowledge Bases: Implement llms.txt and MCP-ready structures to help AI agents and crawlers better understand and navigate complex codebases.
| name | documentation-templates |
|---|---|
| description | Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation. |
| allowed-tools | Read, Glob, Grep |
Documentation Templates
Templates and structure guidelines for common documentation types.
1. README Structure
Essential Sections (Priority Order)
| Section | Purpose |
|---|---|
| Title + One-liner | What is this? |
| Quick Start | Running in <5 min |
| Features | What can I do? |
| Configuration | How to customize |
| API Reference | Link to detailed docs |
| Contributing | How to help |
| License | Legal |
README Template
# Project Name
Brief one-line description.
## Quick Start
[Minimum steps to run]
## Features
- Feature 1
- Feature 2
## Configuration
| Variable | Description | Default |
|----------|-------------|---------|
| PORT | Server port | 3000 |
## Documentation
- [API Reference](./docs/api.md)
- [Architecture](./docs/architecture.md)
## License
MIT
2. API Documentation Structure
Per-Endpoint Template
## GET /users/:id
Get a user by ID.
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | User ID |
**Response:**
- 200: User object
- 404: User not found
**Example:**
[Request and response example]
3. Code Comment Guidelines
JSDoc/TSDoc Template
/**
* Brief description of what the function does.
*
* @param paramName - Description of parameter
* @returns Description of return value
* @throws ErrorType - When this error occurs
*
* @example
* const result = functionName(input);
*/
When to Comment
| ✅ Comment | ❌ Don't Comment |
|---|---|
| Why (business logic) | What (obvious) |
| Complex algorithms | Every line |
| Non-obvious behavior | Self-explanatory code |
| API contracts | Implementation details |
4. Changelog Template (Keep a Changelog)
# Changelog
## [Unreleased]
### Added
- New feature
## [1.0.0] - 2025-01-01
### Added
- Initial release
### Changed
- Updated dependency
### Fixed
- Bug fix
5. Architecture Decision Record (ADR)
# ADR-001: [Title]
## Status
Accepted / Deprecated / Superseded
## Context
Why are we making this decision?
## Decision
What did we decide?
## Consequences
What are the trade-offs?
6. AI-Friendly Documentation (2025)
llms.txt Template
For AI crawlers and agents:
# Project Name
> One-line objective.
## Core Files
- [src/index.ts]: Main entry
- [src/api/]: API routes
- [docs/]: Documentation
## Key Concepts
- Concept 1: Brief explanation
- Concept 2: Brief explanation
MCP-Ready Documentation
For RAG indexing:
- Clear H1-H3 hierarchy
- JSON/YAML examples for data structures
- Mermaid diagrams for flows
- Self-contained sections
7. Structure Principles
| Principle | Why |
|---|---|
| Scannable | Headers, lists, tables |
| Examples first | Show, don't just tell |
| Progressive detail | Simple → Complex |
| Up to date | Outdated = misleading |
Remember: Templates are starting points. Adapt to your project's needs.