documentation-templates – Coding skill for AI agents

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
- Architecture

## License

[Link to the actual project license; do not infer 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 (the example.com links illustrate syntax; replace them with actual published project URLs):

# Project Name
> One-line objective.

## Core Files
- [Main entry](https://example.com/project/src/index.ts): Application entry
- [API routes](https://example.com/project/src/api/): Endpoint implementation
- [Documentation](https://example.com/project/docs/): User and contributor guides

## 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.

When to Use

Use when an actual project needs a README, endpoint reference, changelog, ADR or agent-readable index, and you need a structure adapted to its existing conventions.

Limitations

• Replace illustrative paths, commands, dates and defaults with verified project facts. Templates are not installed workflows or evidence that links and examples work.
• Preserve the actual license and confidentiality scope; do not publish private endpoints or invent accepted ADR decisions.
• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.