Code Documentation

This is a comprehensive reference for writing documentation that developers will actually read. It covers the full spectrum: README templates with quick start sections, JSDoc and OpenAPI specs for APIs, inline commenting guidelines that explain when to comment and when not to, plus architecture decision records. The inline comment examples are especially practical, showing the difference between explaining why you used binary search versus pointlessly commenting that you're incrementing a counter. It also includes that crucial principle that stale docs are worse than no docs. Use this when you're documenting a new API, writing a README for an open source project, or trying to figure out what level of detail your comments actually need.

install copies · 90 days. Times the install command was copied on this site in the last 90 days, bots filtered.: 5
skills.sh installs: 569
GitHub stars: 1.2K
last updated: May 5, 2026

View on GitHub

Install

$ npx -y skills add moizibnyousaf/ai-agent-skills --skill code-documentation --agent claude-code

Installs into .claude/skills of the current project.

Files

Code Documentation

README Structure

Standard README Template

# Project Name

Brief description of what this project does.

## Quick Start

\`\`\`bash
npm install
npm run dev
\`\`\`

## Installation

Detailed installation instructions...

## Usage

\`\`\`typescript
import { something } from 'project';

// Example usage
const result = something.doThing();
\`\`\`

## API Reference

### `functionName(param: Type): ReturnType`

Description of what the function does.

**Parameters:**
- `param` - Description of parameter

**Returns:** Description of return value

**Example:**
\`\`\`typescript
const result = functionName('value');
\`\`\`

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `option1` | `string` | `'default'` | What it does |

## Contributing

How to contribute...

## License

MIT