ReddRadar
Agent skill
readme-craft
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.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/readme-craft
SKILL.md
README Craft
Audience: Developers creating or improving project documentation.
Goal: Generate README files that convert scanners into users within 60 seconds.
Core Philosophy
A README is a sales pitch, onboarding guide, AND reference manual. Lead with value, prove with examples, document with precision.
Common Failures
| 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 |
Golden Structure
Tier 1: Hero Section
<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 |
Tier 3: Quick Example
## 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.
Tier 4: Reference Sections
- Philosophy/Design decisions
- Alternatives comparison
- Installation (multiple methods)
- Command reference
- Configuration options
- Architecture (for complex systems)
Tier 5: Support Sections
- Troubleshooting
- Limitations
- FAQ
- Contributing
- License
Section Templates
Comparison Table
## 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 (Multiple Methods)
## Installation
### Quick Install (Recommended)
```bash
curl -sSL https://example.com/install.sh | bash
Package Managers
# macOS
brew install mytool
# Linux
apt install mytool # Debian/Ubuntu
dnf install mytool # Fedora
# Windows
winget install mytool
From Source
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 run
Execute 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
Error: "Command not found"
Cause: Binary not in PATH.
Fix:
export PATH="$HOME/.local/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrc for persistence
Error: "Config file not found"
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
## 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>
Badge Reference
<!-- CI Status -->
<!-- Version -->
<!-- License -->
<!-- Downloads -->
<!-- Package Managers -->
Progressive Disclosure
For long READMEs (1000+ lines):
<details>
<summary><b>Advanced Configuration</b></summary>
[Detailed content here]
</details>
Or externalize:
docs/CONFIGURATION.mddocs/ARCHITECTURE.mddocs/CONTRIBUTING.md
Keep README focused on the 80% use case.
Pre-Publication Checklist
Hero:
- Logo/image present
- Badges current and working
- One-liner describes the problem solved
- Quick install command visible
Content:
- TL;DR within first scroll
- Every feature has an example
- Code blocks are copy-paste ready
- 3+ installation methods documented
Trust:
- Comparison with alternatives (honest)
- Limitations documented
- Top 5 errors in troubleshooting
- All links verified
Polish:
- Consistent terminology
- No stale badges
- Grammar/spelling checked
Anti-Patterns
| 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 |
Reference Examples
Study these for excellent README patterns:
- ripgrep - Benchmark data, comparison matrices
- bat - Feature highlights, visual demos
- starship - Configuration presets, install matrix
- jq - Tutorial progression, manual linking
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?