What is the purpose of documentation-templates?

To provide ready-made templates and guidelines for common documentation types, ensuring consistency and AI-readiness across projects.

Can templates be adapted for different programming languages?

Yes. The templates include language-agnostic structures (e.g., README, ADR, Changelog) and language-specific examples (JSDoc/TSDoc) that can be customized.

How do AI-friendly docs help my project?

AI-friendly docs use clear hierarchies, self-contained sections, and examples to improve AI indexing, retrieval, and downstream tasks like RAG pipelines.

documentation-templates

Scanned

npx machina-cli add skill vudovn/antigravity-kit/documentation-templates --openclaw

Files (1)

SKILL.md

3.2 KB

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.

Source

git clone https://github.com/vudovn/antigravity-kit/blob/main/.agent/skills/documentation-templates/SKILL.mdView on GitHub

Overview

Provides structured templates and guidelines to standardize project documentation. Covers README structure, API docs, code comments, changelogs, ADRs, and AI-friendly documentation to improve clarity and AI indexing.

How This Skill Works

The skill offers ready-to-fill templates for each documentation type: a README with essential sections, per-endpoint API documentation, a JSDoc/TSDoc style comment template, a changelog and ADR templates, and guidance for AI-friendly docs. You tailor the templates to your project and integrate them into your workflow to ensure consistency across all docs.

When to Use It

Starting a new project and need a complete documentation skeleton (README, API references, and code comments).
Documenting new API endpoints with a standardized per-endpoint template.
Adding or updating code comments using a consistent JSDoc/TSDoc style.
Maintaining changelogs and Architecture Decision Records (ADRs) for traceability.
Structuring AI-friendly documentation to aid RAG indexing and AI crawlers.

Quick Start

Step 1: Identify the needed template (README, API, code comments, changelog, ADR, or AI-friendly docs).
Step 2: Copy the corresponding template from the skill and tailor it to your project specifics.
Step 3: Integrate the templates into your repo (docs folder, CI checks, or templates directory) and keep updating.

Best Practices

Reuse and customize templates across projects to maintain consistency.
Keep sections up to date and reflect the current state of the project.
Use clear headers (H1-H3) and logical structure for AI indexing.
Provide concrete examples (API contracts, code snippets, diagrams) where possible.
Separate concerns: non-obvious business logic should be documented, not trivial code.

Example Use Cases

README with Title + One-liner, Quick Start, Features, Configuration, Documentation links, and License.
API per-endpoint template for GET /users/:id including Parameters, Response, and Example.
JSDoc/TSDoc template illustrating parameter, return value, and example annotations.
Changelog snippet showing Unreleased and versioned sections (Added, Changed, Fixed).
ADR skeleton and AI-friendly documentation layout with core files and key concepts.

Frequently Asked Questions

Add this skill to your agents