Readme Writer

README Writer - Comprehensive Documentation Generator

Use this skill when creating or improving README documentation for any software project. Generates professional, comprehensive READMEs that follow best practices and community standards.

When to Use

• Creating a README for a new project or library
• Improving an outdated or incomplete README
• Standardising README structure across a set of repositories
• Adding installation, usage, API reference, or contribution sections that are missing

Philosophy

A great README is:

• Scannable - Structured with clear headings and hierarchy
• Complete - Answers "what", "why", "how", and "who"
• Actionable - Users can get started in One-line description (the "elevator pitch")

[Badges: build status, version, license, etc.]

Quick Start

[Minimal example to get running in One-line description that explains what this does and why it matters.

[Optional: Screenshot or demo GIF for visual projects]

**Rules**:
- Title matches repository/package name exactly
- One-liner is ** High-performance JSON parser that's 3x faster than JSON.parse() with zero dependencies.

❌ Bad:

# json-parser-new

> This is a JSON parser.

2. Badges

Common badges (only include if accurate):

• Build status (CI/CD)
• Test coverage
• Version/release
• Downloads/installs
• License
• Language/framework version

Format:

[](link)
[](link)
[](link)

Rules:

• Maximum 5-6 badges - more = clutter
• Only include badges with current information
• Link badges to relevant pages
• Align badges horizontally (one line)

3. Quick Start

Purpose: Get a working example in

**Requirements**:
- Node.js >= 18
- Optional: TypeScript >= 5.0 for full type support

Rules:

• Show all common installation methods
• Include system requirements
• Note optional dependencies
• Specify minimum versions
• Add troubleshooting for known issues

For global tools:

## Installation

### Global (recommended)
```bash
npm install -g tool-name

Local (project-specific)

npm install --save-dev tool-name

**For Docker**:
```markdown
## Installation

### Docker
```bash
docker pull user/image:latest
docker run -p 3000:3000 user/image:latest

Docker Compose

curl -o compose.yaml https://example.com/compose.yaml
docker compose up

### 6. Usage

**Purpose**: Show common use cases with real code examples.

**Format**:
```markdown
## Usage

### Basic Example

```javascript
import { createParser } from 'package-name'

const parser = createParser({
  strict: true,
  format: 'json'
})

const result = parser.parse(input)

Advanced Usage

// Custom configuration
const parser = createParser({
  strict: false,
  allowComments: true,
  onError: (err) => console.error(err)
})

// Streaming support
for await (const chunk of parser.stream(largeInput)) {
  process(chunk)
}

Integration with Express

import express from 'express'
import { middleware } from 'package-name'

const app = express()
app.use(middleware())

**Rules**:
- Start simple, progress to complex
- Show real-world use cases
- Include comments for clarity
- Demonstrate key features
- Show expected output when helpful
- Link to full API docs for details

**For CLI tools**:
```markdown
## Usage

### Basic Commands

```bash
# Process a file
tool-name input.txt

# With options
tool-name input.txt --format json --output result.json

# Batch processing
tool-name src/*.txt --output dist/

Common Workflows

# Development
tool-name watch src/ --hot-reload

# Production build
tool-name build --minify --sourcemap

### 7. API Reference

**Purpose**: Complete, structured API documentation.

**Format** (for libraries):
```markdown
## API Reference

### `createParser(options)`

Creates a new parser instance.

**Parameters**:
- `options` (Object) - Configuration options
  - `strict` (boolean) - Enable strict mode. Default: `true`
  - `format` (string) - Output format: `'json'`, `'xml'`, `'yaml'`. Default: `'json'`
  - `onError` (Function) - Error callback. Optional.

**Returns**: `Parser` - Parser instance

**Example**:
```javascript
const parser = createParser({
  strict: true,
  format: 'json'
})

Throws:

• TypeError - If options are invalid
• ConfigError - If format is unsupported

---

parser.parse(input)

Parses input string synchronously.

Parameters:

• input (string) - Input to parse

Returns: ParsedResult - Parsed output

Example:

const result = parser.parse('{"key": "value"}')
console.log(result.key) // "value"

---

Types

interface Parser {
  parse(input: string): ParsedResult
  parseAsync(input: string): Promise
  stream(input: string): AsyncIterator
}

interface ParsedResult {
  data: unknown
  metadata: {
    format: string
    size: number
  }
}

**Format** (for CLI tools):
```markdown
## API Reference

### Commands

#### `tool-name process `

Process a file or directory.

**Arguments**:
- `` - Input file or directory path

**Options**:
- `-o, --output ` - Output path
- `-f, --format ` - Output format (json|xml|yaml)
- `--minify` - Minify output
- `-v, --verbose` - Verbose logging

**Examples**:
```bash
tool-name process input.txt
tool-name process src/ --output dist/ --format json

tool-name watch

Watch for file changes.

Options:

• --hot-reload - Enable hot reload
• --ignore - Ignore pattern (glob)

Example:

tool-name watch src/ --hot-reload --ignore "*.test.js"

Exit Codes

• 0 - Success
• 1 - General error
• 2 - Invalid arguments
• 3 - File not found

**Rules**:
- Document every public API
- Include types/signatures
- Show parameters, return values, exceptions
- Provide examples for each function
- Use consistent formatting
- Link to TypeScript definitions if available

### 8. Configuration

**Purpose**: Document all configuration options.

**Format**:
```markdown
## Configuration

### Configuration File

Create a `.toolrc.json` in your project root:

```json
{
  "format": "json",
  "strict": true,
  "output": "dist/",
  "ignore": ["node_modules", "*.test.js"]
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | TOOL_API_KEY | API key for authentication | - | | TOOL_LOG_LEVEL | Log level: debug, info, warn, error | info | | TOOL_TIMEOUT | Request timeout in milliseconds | 5000 |

Example:

export TOOL_API_KEY=your-key
export TOOL_LOG_LEVEL=debug

Options Reference

| Option | Type | Default | Description | |--------|------|---------|-------------| | strict | boolean | true | Enable strict mode | | format | string | 'json' | Output format | | timeout | number | 5000 | Timeout in ms | | retry | boolean | false | Retry on failure |

**Rules**:
- Show configuration file format
- List all options in a table
- Include environment variables
- Specify types and defaults
- Show examples for complex configs

### 9. Examples

**Purpose**: Comprehensive, real-world examples.

**Format**:
```markdown
## Examples

### Example 1: REST API Integration

```javascript
import { createClient } from 'package-name'

const client = createClient({
  baseURL: 'https://api.example.com',
  apiKey: process.env.API_KEY
})

// Fetch data
const response = await client.get('/users')
console.log(response.data)

// Post data
await client.post('/users', {
  name: 'John Doe',
  email: 'john@example.com'
})

Example 2: Express Middleware

import express from 'express'
import { authMiddleware } from 'package-name'

const app = express()

app.use(authMiddleware({
  secret: process.env.JWT_SECRET,
  expiresIn: '1h'
}))

app.get('/protected', (req, res) => {
  res.json({ user: req.user })
})

app.listen(3000)

Example 3: CI/CD Pipeline

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install
      - run: npx tool-name build --minify

More Examples

See [examples/](./examples/) directory for:

• TypeScript integration example
• React integration example
• Docker deployment example

**Rules**:
- Show complete, runnable examples
- Focus on real-world scenarios
- Include error handling
- Link to full example repositories
- Add comments for clarity

### 10. Troubleshooting

**Purpose**: Common issues and solutions.

**Format**:
```markdown
## Troubleshooting

### Error: "Module not found"

**Cause**: Package not installed or wrong path.

**Solution**:
```bash
npm install package-name

Verify installation:

npm list package-name

---

Error: "TypeError: Cannot read property 'x' of undefined"

Cause: Missing configuration or invalid input.

Solution: Ensure all required options are provided:

const parser = createParser({
  strict: true,  // Required
  format: 'json' // Required
})

---

Performance Issues

Symptom: Slow parsing on large files.

Solution: Use streaming API for large inputs:

for await (const chunk of parser.stream(largeInput)) {
  process(chunk)
}

---

Still having issues?

• Check GitHub Issues
• Ask on Discord
• Create a bug report

**Rules**:
- List most common issues
- Provide clear solutions
- Include error messages verbatim
- Show diagnostic commands
- Link to support channels

### 11. Contributing

**Purpose**: Guide contributors to help with the project.

**Format**:
```markdown
## Contributing

We welcome contributions! Please follow these steps:

### Development Setup

```bash
# Clone the repository
git clone https://github.com/user/repo.git
cd repo

# Install dependencies
npm install

# Run tests
npm test

# Start development server
npm run dev

Making Changes

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add tests for new functionality
5. Run tests: npm test
6. Run linter: npm run lint
7. Commit: git commit -m "feat: add amazing feature"
8. Push: git push origin feature/amazing-feature
9. Open a Pull Request

Commit Convention

We use Conventional Commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• test: - Adding tests
• chore: - Maintenance tasks

Code Style

• Use ESLint config: npm run lint
• Format with Prettier: npm run format
• Write TypeScript with strict mode
• Add JSDoc comments for public APIs

Testing

# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run tests with coverage
npm run test:coverage

Aim for >80% coverage.

Pull Request Guidelines

• Keep PRs focused (one feature/fix per PR)
• Update documentation
• Add tests
• Ensure CI passes
• Link related issues

Code of Conduct

Link to your project's code of conduct when one exists.

Questions?

Join our Discord or open a Discussion.

**Rules**:
- Make setup instructions clear
- Document coding conventions
- Explain commit message format
- Link to Code of Conduct
- Provide support channels

### 12. License

**Purpose**: Legal information.

**Format**:
```markdown
## License

MIT License - see [LICENSE](LICENSE) file for details.

Copyright (c) 2025 [Your Name/Organization]

Rules:

• State license type clearly
• Link to LICENSE file
• Include copyright notice

Special README Types

Library/Package README

Focus: API documentation, installation, usage examples.

Must include:

• Installation (npm/yarn/pnpm)
• Quick start example
• Complete API reference
• TypeScript types
• Browser/Node compatibility
• Bundle size
• Performance benchmarks

CLI Tool README

Focus: Commands, options, workflows.

Must include:

• Installation (global + local)
• Command reference
• Exit codes
• Configuration files
• Common workflows
• Piping and scripting examples

Application README

Focus: Setup, running, deployment.

Must include:

• Prerequisites (Node version, etc.)
• Environment variables
• Database setup
• Development workflow
• Production deployment
• Docker instructions

Framework/Boilerplate README

Focus: Features, structure, getting started.

Must include:

• Tech stack overview
• Project structure
• Getting started guide
• Customization options
• Deployment options
• Migration guides

Internal Tool README

Focus: Purpose, team usage, maintenance.

Must include:

• Why this exists (problem solved)
• Who maintains it
• How to use it
• How to deploy updates
• Known limitations
• Runbooks/troubleshooting

README Writing Process

Step 1: Analyze the Project

Gather information:

• Read existing documentation
• Examine package.json / setup.py / Cargo.toml
• Review source code structure
• Check for configuration files
• Identify framework/language
• Note dependencies
• Review issues/PRs for common questions

Determine README type: Library? CLI? Application? Framework?

Step 2: Identify Target Audience

Ask:

• Who will use this?
• What's their experience level?
• What do they need to accomplish?
• What context can I assume?

Tailor content:

• Beginners: More explanation, simpler examples
• Experts: Concise, focus on advanced features
• Mixed: Progressive disclosure (basics → advanced)

Step 3: Draft the Structure

Create outline:

1. Title + description
2. Quick start (always)
3. Features
4. Installation
5. Usage (basic → advanced)
6. API reference (if applicable)
7. Configuration
8. Examples
9. Troubleshooting
10. Contributing
11. License

Adapt structure based on project type.

Step 4: Write Section by Section

For each section:

• Start with the goal (what does the reader need?)
• Write actionable content (code over prose)
• Use examples liberally
• Test code examples (ensure they work)
• Format for scannability

Step 5: Add Visual Elements

When helpful:

• Screenshots for UIs
• GIFs for CLI demos
• Diagrams for architecture
• Tables for comparisons
• Code blocks with syntax highlighting

Tools:

• Screenshots: OS native tools
• GIFs: terminalizer, asciinema
• Diagrams: Mermaid, Excalidraw

Step 6: Review and Polish

Checklist:

• [ ] All code examples work (tested)
• [ ] Links are valid
• [ ] Grammar/spelling checked
• [ ] Formatting consistent
• [ ] No outdated information
• [ ] Mobile-friendly (GitHub renders well)
• [ ] Accessibility (alt text for images)

Test the README:

• Follow your own quick start
• Ask a colleague to review
• Check on different devices

Advanced Techniques

Progressive Disclosure

Principle: Show essential info first, hide details until needed.

Example:

## Quick Start

```bash
npm install tool-name
tool-name input.txt

Advanced configuration options

Configuration File

Create .toolrc.json:

{
  "format": "json",
  "strict": true,
  "plugins": []
}

See [full configuration reference](#configuration).

### Comparison Tables

**When to use**: Comparing features, packages, approaches.

**Example**:
```markdown
## Why This Package?

| Feature | This Package | Alternative A | Alternative B |
|---------|--------------|---------------|---------------|
| Bundle size | 2KB | 50KB | 12KB |
| TypeScript | ✅ Full | ⚠️ Partial | ❌ No |
| Zero deps | ✅ Yes | ❌ No | ✅ Yes |
| Performance | 3x faster | B

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [brpaz](https://github.com/brpaz)
- **Source:** [brpaz/agent-skills](https://github.com/brpaz/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.