home / skills / vudovn / antigravity-kit / documentation-templates

documentation-templates skill

safe

This skill helps you generate clear README, API, and code comment templates to standardize docs across TypeScript projects.

npx playbooks add skill vudovn/antigravity-kit --skill documentation-templates

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.2 KB

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

```markdown
# 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

```markdown
## 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

```typescript
/**
 * 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)

```markdown
# 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)

```markdown
# 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:

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

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

FAQ

How should I adapt these templates to my project?

Use the templates as starting points: keep sections that add value, remove irrelevant ones, and align naming with your repo and CI/CD conventions.

What makes documentation AI-friendly?

Clear H1–H3 hierarchy, self-contained sections, structured examples (JSON/YAML), and a small manifest (llms.txt) pointing to core files improve agent indexing and retrieval.

When should I write an ADR?

Create an ADR whenever a decision affects architecture, APIs, or major trade-offs—ideally before implementation or immediately after to capture rationale.