# Readme Writer

> Create and improve README files with structured installation, usage, API, and contribution guidance.

- **Type:** Skill
- **Install:** `agentstack add skill-brpaz-agent-skills-readme-writer`
- **Verified:** Pending review
- **Seller:** [brpaz](https://agentstack.voostack.com/s/brpaz)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [brpaz](https://github.com/brpaz)
- **Source:** https://github.com/brpaz/agent-skills/tree/main/skills/readme-writer

## Install

```sh
agentstack add skill-brpaz-agent-skills-readme-writer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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**:
```markdown
# 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**:
```markdown
[](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**:
```markdown
## Installation

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

### Local (project-specific)
```bash
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
```bash
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

```javascript
// 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

```javascript
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

```bash
# 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**:
```javascript
const result = parser.parse('{"key": "value"}')
console.log(result.key) // "value"
```

---

### Types

```typescript
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**:
```bash
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**:
```bash
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

```javascript
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

```yaml
# .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:
```bash
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:
```javascript
const parser = createParser({
  strict: true,  // Required
  format: 'json' // Required
})
```

---

### Performance Issues

**Symptom**: Slow parsing on large files.

**Solution**:
Use streaming API for large inputs:
```javascript
for await (const chunk of parser.stream(largeInput)) {
  process(chunk)
}
```

---

### Still having issues?

- Check [GitHub Issues](https://github.com/user/repo/issues)
- Ask on [Discord](https://discord.gg/community)
- Create a [bug report](https://github.com/user/repo/issues/new)
```

**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](https://www.conventionalcommits.org/):

- `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

```bash
# 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](https://discord.gg/community) or open a [Discussion](https://github.com/user/repo/discussions).
```

**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](https://github.com/faressoft/terminalizer), [asciinema](https://asciinema.org/)
- Diagrams: [Mermaid](https://mermaid.js.org/), [Excalidraw](https://excalidraw.com/)

### 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**:
```markdown
## Quick Start

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

Advanced configuration options

### Configuration File

Create `.toolrc.json`:
```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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-brpaz-agent-skills-readme-writer
- Seller: https://agentstack.voostack.com/s/brpaz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.