/code-documentation

name: code-documentation
description: Use this skill when the user requests to generate, create, or improve documentation for code, APIs, libraries, repositories, or software projects. Supports README generation, API reference documentation, inline code comments, architecture documentation, changelog generation, and developer guides. Trigger on requests like "document this code", "create a README", "generate API docs", "write developer guide", or when analyzing codebases for documentation purposes.

Code Documentation Skill

Overview

This skill generates professional, comprehensive documentation for software projects, codebases, libraries, and APIs. It follows industry best practices from projects like React, Django, Stripe, and Kubernetes to produce documentation that is accurate, well-structured, and useful for both new contributors and experienced developers.

The output ranges from single-file READMEs to multi-document developer guides, always matched to the project's complexity and the user's needs.

Core Capabilities

• Generate comprehensive README.md files with badges, installation, usage, and API reference
• Create API reference documentation from source code analysis
• Produce architecture and design documentation with diagrams
• Write developer onboarding and contribution guides
• Generate changelogs from commit history or release notes
• Create inline code documentation following language-specific conventions
• Support JSDoc, docstrings, GoDoc, Javadoc, and Rustdoc formats
• Adapt documentation style to the project's language and ecosystem

When to Use This Skill

**Always load this skill when:**

• User asks to "document", "create docs", or "write documentation" for any code
• User requests a README, API reference, or developer guide
• User shares a codebase or repository and wants documentation generated
• User asks to improve or update existing documentation
• User needs architecture documentation, including diagrams
• User requests a changelog or migration guide

Documentation Workflow

Phase 1: Codebase Analysis

Before writing any documentation, thoroughly understand the codebase.

Step 1.1: Project Discovery

Identify the project fundamentals:

| Field | How to Determine | |-------|-----------------| | **Language(s)** | Check file extensions, `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc. | | **Framework** | Look at dependencies for known frameworks (React, Django, Express, Spring, etc.) | | **Build System** | Check for `Makefile`, `CMakeLists.txt`, `webpack.config.js`, `build.gradle`, etc. | | **Package Manager** | npm/yarn/pnpm, pip/uv/poetry, cargo, go modules, etc. | | **Project Structure** | Map out the directory tree to understand the architecture | | **Entry Points** | Find main files, CLI entry points, exported modules | | **Existing Docs** | Check for existing README, docs/, wiki, or inline documentation |

Step 1.2: Code Structure Analysis

Use sandbox tools to explore the codebase:

# Get directory structure
ls /mnt/user-data/uploads/project-dir/

# Read key files
read_file /mnt/user-data/uploads/project-dir/package.json
read_file /mnt/user-data/uploads/project-dir/pyproject.toml

# Search for public API surfaces
grep -r "export " /mnt/user-data/uploads/project-dir/src/
grep -r "def " /mnt/user-data/uploads/project-dir/src/ --include="*.py"
grep -r "func " /mnt/user-data/uploads/project-dir/ --include="*.go"

Step 1.3: Identify Documentation Scope

Based on analysis, determine what documentation to produce:

| Project Size | Recommended Documentation | |-------------|--------------------------| | **Single file / script** | Inline comments + usage header | | **Small library** | README with API reference | | **Medium project** | README + API docs + examples | | **Large project** | README + Architecture + API + Contributing + Changelog |

Phase 2: Documentation Generation

Step 2.1: README Generation

Every project needs a README. Follow this structure:

# Project Name

[One-line project description — what it does and why it matters]

[![Badge](link)](#) [![Badge](link)](#)

## Features

- [Key feature 1 — brief description]
- [Key feature 2 — brief description]
- [Key feature 3 — brief description]

## Quick Start

### Prerequisites

- [Prerequisite 1 with version requirement]
- [Prerequisite 2 with version requirement]

### Installation

[Installation commands with copy-paste-ready code blocks]

### Basic Usage

[Minimal working example that demonstrates core functionality]

## Documentation

- [Link to full API reference if separate]
- [Link to architecture docs if separate]
- [Link to examples directory if applicable]

## API Reference

[Inline API reference for smaller projects OR link to generated docs]

## Configuration

[Environment variables, config files, or runtime options]

## Examples

[2-3 practical examples covering common use cases]

## Development

### Setup

[How to set up a development environment]

### Testing

[How to run tests]

### Building

[How to build the project]

## Contributing

[Contribution guidelines or link to CONTRIBUTING.md]

## License

[License information]

Step 2.2: API Reference Generation

For each public API surface, document:

**Function / Method Documentation**:

### `functionName(param1, param2, options?)`

Brief description of what this function does.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `param1` | `string` | Yes | — | Description of param1 |
| `param2` | `number` | Yes | — | Description of param2 |
| `options` | `Object` | No | `{}` | Configuration options |
| `options.timeout` | `number` | No | `5000` | Timeout in milliseconds |

**Returns:** `Promise<Result>` — Description of return value

**Throws:**
- `ValidationError` — When param1 is empty
- `TimeoutError` — When the operation exceeds the timeout

**Examp