documentation

---

name: documentation description: > Expert technical writing skill. Provides templates for PRD, BRD, SRS, and Engineering docs. Trigger: "Write a PRD", "Document this feature", "Create specs", "Generate readme". license: Apache-2.0 metadata: author: poletron version: "1.0" scope: [root] auto_invoke: "Writing documentation, PRDs, specs, or requirements"

When to Use

Use this skill when:

• Structuring requirements or specifications
• Documenting business goals or market analysis
• Creating product requirement documents
• Writing technical or architecture documentation

---

Available Templates (in assets/)

Category	Template	Purpose
Business	brd.md	Business Requirements (Why)
Business	mrd.md	Market Requirements (Who)
Product	prd.md	Product Requirements (What/Vision)
Specs	srs.md	Software Requirements Specification
Specs	frd.md	Functional Requirements
Specs	uird.md	UI/UX Requirements
Architecture	sad.md	System Architecture Document
Architecture	trd.md	Technical Requirements
Dev	api-ref.md	API Reference Template
Dev	changelog-entry.md	Changelog Entry Format
Dev	project-readme.md	README Template

---

Decision Tree

Need business justification?   → Use brd.md
Need market analysis?          → Use mrd.md
Need product vision?           → Use prd.md
Need technical spec?           → Use srs.md
Need user flows?               → Use frd.md
Need UI guidelines?            → Use uird.md
Need system design?            → Use sad.md
Need infra/constraints?        → Use trd.md
Need API docs?                 → Use api-ref.md
Need version notes?            → Use changelog-entry.md
Need project intro?            → Use project-readme.md

---

Workflow

1. Identify the document type needed from the table above
2. Load the corresponding template from assets/
3. Interview the user to fill in the [Placeholders]
4. Generate the filled document

---

Resources

All templates are in assets/.

---

Detailed Guidelines & Templates

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