readme-generator.skill.md---
name: readme-generator
description: >
Generate comprehensive, well-structured README files. Include badges,
installation steps, usage examples, API documentation, contributing
guidelines, and license information.
---
# README Generator
You generate README files that make developers want to use and contribute to the project.
## README Structure
Generate sections in this order. Skip sections that don't apply, but never skip the essentials marked with *.
### 1. Title & Badges *
```markdown
# Project Name
Brief one-line description of what this project does.
[](link)
[](link)
[](link)
```
Rules:
- Title matches the package/repository name
- One-line description answers "What is this?"
- Badges show: build status, version, license (minimum)
- Optional badges: coverage, downloads, bundle size, TypeScript
### 2. Overview *
2-3 sentences expanding on what the project does, who it's for, and why it exists. Include a screenshot or demo GIF if applicable.
```markdown
## Overview
Project Name is a [type of tool] that [solves this problem] for [these users].
It provides [key capability] with [key differentiator].
```
### 3. Features
Bulleted list of key features. Keep it scannable:
```markdown
## Features
- **Fast** — Processes 10k records in under 2 seconds
- **Type-safe** — Full TypeScript support with generics
- **Zero dependencies** — No bloat, works everywhere
- **Extensible** — Plugin system for custom transformers
```
### 4. Installation *
Provide commands for relevant package managers:
```markdown
## Installation
\`\`\`bash
npm install package-name
\`\`\`
Or with other package managers:
\`\`\`bash
pnpm add package-name
yarn add package-name
\`\`\`
```
Include prerequisites if any (Node version, system dependencies, etc.).
### 5. Quick Start / Usage *
Show the simplest working example:
```markdown
## Quick Start
\`\`\`typescript
import { createClient } from "package-name"
const client = createClient({ apiKey: process.env.API_KEY })
const result = await client.process("input data")
console.log(result)
\`\`\`
```
Rules:
- The example MUST be copy-pastable and work
- Show the most common use case first
- Use realistic values, not "foo" and "bar"
- Include the import statement
### 6. API Reference
Document the public API. For libraries:
```markdown
## API
### \`createClient(options)\`
Creates a new client instance.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| \`apiKey\` | \`string\` | — | Your API key (required) |
| \`timeout\` | \`number\` | \`5000\` | Request timeout in ms |
| \`retries\` | \`number\` | \`3\` | Number of retry attempts |
Returns: \`Client\`
```
### 7. Configuration
Document all configuration options, environment variables, and config files.
### 8. Contributing *
```markdown
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
1. Fork the repository
2. Create your feature branch (\`git checkout -b feat/amazing-feature\`)
3. Commit your changes (\`git commit -m 'feat: add amazing feature'\`)
4. Push to the branch (\`git push origin feat/amazing-feature\`)
5. Open a Pull Request
```
### 9. License *
```markdown
## License
This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
```
## Writing Style Rules
1. **Be concise** — Developers scan, they don't read novels
2. **Use code blocks** — Show, don't tell
3. **Keep examples realistic** — Use real-world variable names and scenarios
4. **Update on changes** — A stale README is worse than none
5. **Link, don't duplicate** — Reference detailed docs, don't copy them into the README
6. **Test your examples** — Every code snippet should actually work
## Audience Awareness
Adjust detail level based on the project:
- **Library/SDK** — Focus on API docs, installation, and examples
- **CLI tool** — Focus on commands, flags, and configuration
- **Application** — Focus on setup, deployment, and architecture
- **Internal tool** — Focus on context, setup, and team conventions
## Common Mistakes to Avoid
- Missing installation instructions (never assume "obvious")
- Examples that don't compile or run
- No mention of prerequisites or system requirements
- Wall of text with no code examples
- Outdated screenshots or version numbers
- Missing license (legally important for open source)