Production-grade README.md patterns for any project type. Use when creating project documentation, writing README files, or improving existing docs. Covers hero sections, quick start examples, comparison tables, troubleshooting guides, and limitation transparency. Triggers on README, documentation, project setup, open source.
/plugin marketplace add majesticlabs-dev/majestic-marketplace/plugin install majestic-engineer@majestic-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/section-templates.mdAudience: Developers creating or improving project documentation.
Goal: Generate README files that convert scanners into users within 60 seconds.
A README is a sales pitch, onboarding guide, AND reference manual. Lead with value, prove with examples, document with precision.
| Failure | Fix |
|---|---|
| Installation first | Lead with TL;DR and value prop |
| Describes what it IS | Describe what problem it SOLVES |
| No examples | One example per feature minimum |
| Hidden limitations | Dedicated limitations section |
| Single install method | Three+ pathways (curl, package manager, source) |
| No troubleshooting | Document top 5 common errors |
<p align="center">
<img src="logo.png" width="200" alt="Project Name">
</p>
<p align="center">
<a href="..."><img src="https://img.shields.io/..." alt="CI"></a>
<a href="..."><img src="https://img.shields.io/..." alt="Version"></a>
<a href="..."><img src="https://img.shields.io/..." alt="License"></a>
</p>
<p align="center">
<b>One-line description of what problem this solves</b>
</p>
```bash
curl -sSL https://example.com/install.sh | bash
### Tier 2: TL;DR
```markdown
## TL;DR
**Problem:** [Specific pain point users face]
**Solution:** [How this tool solves it]
| Feature | Benefit |
|---------|---------|
| Feature 1 | Quantified benefit |
| Feature 2 | Quantified benefit |
| Feature 3 | Quantified benefit |
## Quick Start
# 1. Install
curl -sSL https://example.com/install.sh | bash
# 2. Initialize
mytool init
# 3. Run core workflow
mytool process input.txt --output result.json
# 4. Verify
mytool status
Rule: 5-10 commands demonstrating the core workflow.
## Why [Tool] Over Alternatives?
| Feature | [Tool] | Alternative A | Alternative B |
|---------|--------|---------------|---------------|
| Speed | 50ms | 200ms | 150ms |
| Memory | 10MB | 50MB | 30MB |
| Feature X | Yes | No | Partial |
| Feature Y | Yes | Yes | No |
**Choose [Tool] when:** [specific use case]
**Choose Alternative A when:** [specific use case]
## Installation
### Quick Install (Recommended)
```bash
curl -sSL https://example.com/install.sh | bash
# macOS
brew install mytool
# Linux
apt install mytool # Debian/Ubuntu
dnf install mytool # Fedora
# Windows
winget install mytool
git clone https://github.com/user/mytool
cd mytool
make install
### Command Reference
```markdown
## Commands
### Global Flags
| Flag | Description |
|------|-------------|
| `-v, --verbose` | Increase output verbosity |
| `-q, --quiet` | Suppress non-error output |
| `--config PATH` | Use custom config file |
### `mytool init`
Initialize a new project.
```bash
mytool init # Interactive setup
mytool init --template minimal # Use template
mytool init --force # Overwrite existing
mytool runExecute the main workflow.
mytool run input.txt # Basic usage
mytool run -o output.json # Custom output
mytool run --dry-run # Preview changes
### Troubleshooting
```markdown
## Troubleshooting
### Error: "Permission denied"
**Cause:** Installation script lacks execute permissions.
**Fix:**
```bash
chmod +x install.sh
./install.sh
Cause: Binary not in PATH.
Fix:
export PATH="$HOME/.local/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrc for persistence
Cause: Missing configuration.
Fix:
mytool init --config
### Limitations
```markdown
## Limitations
**Current constraints:**
| Limitation | Workaround | Planned Fix |
|------------|------------|-------------|
| Max 10MB files | Split large files | v2.0 |
| No Windows GUI | Use WSL | Under review |
| Single-threaded | Use multiple instances | v1.5 |
**Out of scope:**
- Feature X (use [Alternative] instead)
- Feature Y (not planned)
## FAQ
<details>
<summary><b>Q: How does this compare to [Alternative]?</b></summary>
[Tool] focuses on [specific strength], while [Alternative] excels at [different use case]. Choose [Tool] when you need [criteria].
</details>
<details>
<summary><b>Q: Can I use this in production?</b></summary>
Yes. [Tool] is used in production by [companies/projects]. See our [stability policy](link).
</details>
<!-- CI Status -->
<!-- Version -->
<!-- License -->
<!-- Downloads -->
<!-- Package Managers -->
For long READMEs (1000+ lines):
<details>
<summary><b>Advanced Configuration</b></summary>
[Detailed content here]
</details>
Or externalize:
docs/CONFIGURATION.mddocs/ARCHITECTURE.mddocs/CONTRIBUTING.mdKeep README focused on the 80% use case.
Hero:
Content:
Trust:
Polish:
| Do NOT | Do Instead |
|---|---|
| Start with installation | Start with value proposition |
| "This tool is a..." | "This tool solves..." |
| Screenshot-only demos | Executable code blocks |
| Claim without example | Example per feature |
| Hide limitations | Dedicated section |
| Single install method | Multiple pathways |
| Ignore errors | Troubleshooting section |
Study these for excellent README patterns:
This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.