home / skills / sickn33 / antigravity-awesome-skills / documentation-templates

documentation-templates skill

safe

This skill provides ready-to-use documentation templates and structure guidelines for README, API docs, code comments, and AI-friendly docs.

This is most likely a fork of the documentation-templates skill from vudovn

npx playbooks add skill sickn33/antigravity-awesome-skills --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 structural guidelines for README files, API docs, code comments, changelogs, ADRs, and AI-friendly documentation. It helps teams produce scannable, consistent, and agent-friendly docs that speed onboarding and enable reliable RAG indexing. Use the templates as practical starting points and adapt them to your project conventions.

How this skill works

The skill supplies short, prioritized templates for common documentation types: README, per-endpoint API docs, JSDoc/TSDoc-style code comments, changelogs, ADRs, and llms.txt for AI crawlers. It also prescribes structural principles (scannable headings, examples-first, progressive detail) and concrete artifacts (JSON/YAML examples, Mermaid diagrams) that improve machine and human consumption. Implement the templates directly in your docs repository and iterate to match project needs.

When to use it

Bootstrapping a new project README and Quick Start
Standardizing API docs across services or endpoints
Adding consistent code comments and examples for maintainability
Preparing docs for RAG/agent ingestion or AI crawlers
Capturing architectural decisions and changelogs

Best practices

Prioritize a one-line description and Quick Start at the top of README
Keep API endpoint docs per-endpoint with parameters, responses, and examples
Comment to explain why or business intent; avoid restating obvious code
Use H1–H3 hierarchy, JSON/YAML examples, and Mermaid diagrams for AI-friendly indexing
Maintain a changelog and ADRs to record decisions and trade-offs

Example use cases

Create a README template that includes Quick Start, Features, Configuration table, and links to API docs
Document each REST endpoint with parameters, response codes, and a sample request/response
Apply JSDoc/TSDoc blocks for public functions with @param, @returns, and @example
Add llms.txt listing core files and key concepts to aid AI crawlers and RAG pipelines
Record major design decisions with ADRs and publish an up-to-date changelog

FAQ

Can I adapt these templates to a monorepo?

Yes. Keep the same structure but add workspace-specific Quick Start sections and per-package API links. Use a top-level llms.txt to point agents at package entry points.

How do I keep docs up to date?

Integrate doc checks into CI (linting, link checks), require doc updates in PR templates, and tie changelog/ADR updates to relevant PRs so documentation evolves with code.