name

description

license

metadata

product-readme

Creates polished, product-quality README.md files for open source projects. Use when user asks to "write a README", "productize the README", "make the README look professional", "add screenshots to README", or wants to improve an existing README's presentation and structure.

MIT

author

version

Product README

Create product-quality README.md files that make open source projects look professional, trustworthy, and easy to adopt. The README is the landing page of your project -- treat it like a product page, not a technical spec.

Writing Tone

Apply these voice and style rules to all README content you write:

Second person, direct. "You" not "the user." "Run the command" not "The command should be run."
Present tense. "Processes images" not "Will process images."
Active voice. "PixFix detects the grid" not "The grid is detected by PixFix."
Plain language over jargon. If a term only makes sense to someone who already understands the project, rephrase it. The README is for people who don't know the project yet.
Confident, not salesy. State what it does directly. No "revolutionary", "blazing fast", "powerful" -- let the features speak. If it's fast, show a benchmark. If it's easy, show a 3-line quick start.
Concise. Every sentence should earn its place. If removing a sentence doesn't lose information, remove it.
Consistent terminology. Pick one term for each concept and stick with it throughout. Don't alternate between "image", "file", "input", and "asset" for the same thing.
Code over prose. When you can show a command instead of describing it, show the command. projectname input.png communicates more than "Pass your input file as the first argument to the projectname binary."

Instructions

Step 1: Audit the Project

Before writing, understand what you're working with:

Read the existing README (if any) and note what's missing or weak
Identify the project type: CLI tool, desktop app, library, web app, API, etc.
Check for existing screenshots in the repo (look in assets/, screenshots/, docs/, .github/)
Read the main source files to understand what the project actually does
Check for an existing logo or banner in the repo

Step 2: Determine the README Structure

Use this exact section order. Every section is not required for every project -- skip sections that don't apply, but never reorder them.

<!-- 1. Banner/Logo (if available) -->
<!-- 2. Project title (h1) -->
<!-- 3. One-line description (italic or blockquote) -->
<!-- 4. Badges row -->
<!-- 5. Hero screenshot or demo GIF -->
<!-- 6. Features list (bullet points, keep to 4-8) -->
<!-- 7. Quick start / Installation -->
<!-- 8. Usage (with screenshots for GUI apps) -->
<!-- 9. Configuration / Options reference -->
<!-- 10. CLI reference (if applicable) -->
<!-- 11. Architecture / How it works (brief) -->
<!-- 12. Contributing -->
<!-- 13. License -->

Step 3: Write the Header Block

The header is the most important part. Users decide in 5 seconds whether to keep reading.

Title: Use the project name as an h1. If there's a logo/banner, place it above the title centered:

<div align="center">
  <img src="assets/banner.png" alt="ProjectName" width="600">

  *One-line description that explains what this does and why you'd want it.*

  [![License](https://img.shields.io/badge/license-MIT-blue.svg)](...)
  [![Version](https://img.shields.io/github/v/release/user/repo)](...)
  [![Build](https://img.shields.io/github/actions/workflow/status/user/repo/ci.yml)](...)
</div>

Description rules:

One sentence, max two. Written for someone who has never heard of this project.
Focus on the outcome, not the implementation. "Clean up AI-generated pixel art into game-ready sprites" not "Rust CLI tool that applies grid detection and color quantization algorithms"
Use italic or a blockquote style for visual distinction

Badge rules:

Maximum 3-5 badges on one line
Only include badges that provide useful signal: license, version/release, build status, platform
Use shields.io for consistent styling
Prefer flat or flat-square style -- pick one and be consistent
Do NOT include badges for: code coverage (unless >90%), downloads (unless impressive), "made with X" vanity badges

Step 4: Hero Visual

CRITICAL: Every project with a GUI or visual output MUST have a hero screenshot immediately after the badges.

Screenshot tools (recommend one based on user's platform):

Tool	Platform	Why
Xnapper	macOS	Auto-adds padding, rounded corners, clean backgrounds. Auto-hides sensitive info. Best for polished product shots.
CleanShot X	macOS	Similar to Xnapper with annotation tools and scrolling capture.
ShareX	Windows	Free, open source. Custom workflows, auto-upload, annotation.
Flameshot	Linux	Free, open source. Annotation, region select, clipboard/file save.
Browser DevTools	Any	Built-in device emulation screenshots for web apps. `Cmd+Shift+P` > "Capture screenshot" in Chrome.

Screenshot guidelines:

Whichever tool you use, apply consistent styling across all screenshots (same background, padding, corner radius)
Place screenshots in a dedicated folder: assets/screenshots/ or .github/screenshots/
Name screenshots descriptively: main-interface.png, before-after-comparison.png, dark-mode.png -- never screenshot1.png or X3fG2.png
Optimize image size: screenshots should be under 500KB each. Use ImageOptim or similar.
For the hero screenshot, use width constraint in markdown:

<div align="center">
  <img src="assets/screenshots/main-interface.png" alt="ProjectName main interface" width="700">
</div>

Screenshot content priorities:

For desktop/web apps: show the main UI in its best state (with real-looking data, not empty state)
For CLI tools: show terminal output with a compelling example (use a dark terminal theme)
For before/after tools: show a side-by-side comparison
For libraries: show a minimal code example + its output

When screenshots don't exist yet:

Recommend a screenshot tool from the table above based on the user's platform
Suggest specific screenshots they should capture and where each goes in the README
Add placeholder comments in the README: 
Never use placeholder images or stock photos

Step 4b: Demo GIFs and Videos

A short demo GIF or video can be more persuasive than any amount of text. Use one when the project involves a visual workflow, interactive UI, or a CLI with satisfying output.

When to use a demo GIF vs screenshot vs video:

Format	Best for	Max length	Max size
Static screenshot	UI that speaks for itself, before/after comparisons	n/a	500KB
GIF	Short workflows, CLI demos, "watch it work" moments	15 seconds	5MB
Video (MP4 linked)	Longer tutorials, complex multi-step workflows	2 minutes	Link externally

Recording tools:

Tool	Platform	Type	Notes
vhs	Any	CLI demo	Write a `.tape` script, renders to GIF. Perfect for reproducible CLI demos.
asciinema	Any	CLI demo	Records terminal sessions. Can embed as a player or export to GIF/SVG.
gifski	Any	GIF encoder	Converts video frames to high-quality GIF. Pairs with any screen recorder.
Kap	macOS	Screen recorder	Simple, exports to GIF/MP4. Good for GUI app demos.
LICEcap	macOS/Windows	Screen recorder	Records directly to GIF. Lightweight.
OBS Studio	Any	Screen recorder	Full-featured, exports to MP4. Convert to GIF with gifski for README.
peek	Linux	Screen recorder	Simple GIF/MP4 recorder for Linux desktops.

Demo GIF best practices:

Keep it under 15 seconds. If it takes longer, you're showing too much -- split into multiple GIFs or link a video.
Show a complete workflow: input -> action -> result. Don't start mid-flow.
Use a clean terminal/desktop. Close unrelated tabs, hide bookmarks bar, use a neutral wallpaper.
For CLI demos: use a slightly larger font size than normal so it's readable at README width.
Optimize aggressively. A 20MB GIF will make the README painful to load. Target under 5MB.
- Reduce frame rate (10-15fps is fine for demos)
- Reduce resolution (800px wide is sufficient)
- Use gifski for quality-optimized compression
Place the demo GIF in the same location as the hero screenshot (after badges, centered):

<div align="center">
  <img src="assets/demo.gif" alt="ProjectName demo showing the full processing workflow" width="700">
</div>

For longer videos:

Host on YouTube, Vimeo, or as a GitHub release asset
Embed a thumbnail/screenshot in the README that links to the video:

<div align="center">
  <a href="https://www.youtube.com/watch?v=VIDEO_ID">
    <img src="assets/screenshots/video-thumbnail.png" alt="Watch the demo" width="600">
  </a>
  <br>
  <em>Click to watch the full demo (2 min)</em>
</div>

vhs tape file example (for CLI tools):

# demo.tape
Output assets/demo.gif
Set FontSize 16
Set Width 800
Set Height 500
Set Theme "Catppuccin Mocha"

Type "projectname input.png --palette lospec:endesga-32"
Enter
Sleep 3s

Step 5: Features Section

Write a scannable features list. This is NOT a changelog or technical spec.

## Features

- **Grid-aligned cleanup** -- Snaps messy AI art to a clean pixel grid
- **Smart color reduction** -- Quantizes to any palette using perceptual color science
- **Batch processing** -- Process entire folders with parallel execution
- **Sprite sheet support** -- Split, process, and reassemble sprite sheets

Rules:

4-8 bullet points maximum. If you have more, you're listing implementation details, not features.
Bold the feature name, then explain the benefit after an em dash
Lead with the user benefit, not the technical mechanism
Order by "wow factor" -- most impressive/unique features first
Never start bullets with "Supports..." -- that's passive. Use active verbs.

Step 6: Quick Start / Installation

Get the user from zero to running in the fewest possible steps.

## Quick Start

### Install

```bash
# macOS
brew install projectname

# From source
cargo install projectname

Run

projectname input.png -o output.png


Rules:
- Show the fastest path first (brew/npm/pip before building from source)
- Use real, working commands -- test them before committing
- If there are prerequisites (Rust toolchain, Node.js, etc.), list them in a collapsible details block:

```markdown
<details>
<summary>Prerequisites</summary>

- Rust 1.70+ (`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`)
- libpng development headers (`brew install libpng` on macOS)

</details>

Step 7: Usage Section

For GUI apps, this section should be screenshot-heavy. For CLI tools, show real command examples.

For GUI/desktop apps:

Screenshot per major workflow or feature
Brief caption under each screenshot explaining what the user is seeing
Order screenshots by typical user flow (open -> configure -> process -> save)

For CLI tools:

Show 3-5 real command examples, starting simple and getting more advanced
Include expected output where helpful (truncated if verbose)
Use comments in code blocks to explain flags

## Usage

### Basic

```bash
# Process a single image with auto-detected grid
projectname input.png

# Specify grid size and output palette
projectname input.png --grid-size 8 --palette lospec:endesga-32 -o clean.png

Batch Processing

# Process all PNGs in a directory
projectname batch input_dir/ -o output_dir/


### Step 8: Options/Configuration Reference

For projects with many CLI flags or configuration options, use a table:

```markdown
## Options

| Flag | Default | Description |
|------|---------|-------------|
| `-g, --grid-size` | auto | Pixel grid size (auto-detected if omitted) |
| `-p, --palette` | - | Target palette (name or path) |
| `-o, --output` | `{input}_clean.png` | Output path |
| `--no-aa` | false | Skip anti-aliasing removal |

Alphabetize or group logically
Show defaults
Keep descriptions to one line
For config files, show a minimal annotated example, then link to full reference in a docs/ folder

Step 9: Architecture / How It Works (Optional)

Include only if the project does something non-obvious that users would be curious about. Keep it brief (1-2 paragraphs + optional diagram). This is for users who want to trust the tool, not for contributors.

## How It Works

ProjectName runs a 5-stage pipeline on each image:

1. **Grid detection** -- Finds the pixel grid size by scoring edge alignment
2. **AA removal** -- Removes anti-aliasing using perceptual color distance
3. **Snap to grid** -- Votes on the dominant color per grid cell
4. **Color quantization** -- Reduces palette using k-means in OKLAB color space
5. **Background removal** -- Identifies and removes uniform backgrounds

Step 10: Audience Prioritization

Structure the README so different audiences find what they need:

Priority 1 -- Users who want to try it (top of README):

What does it do? (hero screenshot + description)
How do I install it? (quick start)
How do I use it? (basic usage)

Priority 2 -- Users evaluating it (middle of README):

Full feature list
Configuration options
Comparison to alternatives (if relevant, be fair)

Priority 3 -- Developers/contributors (bottom or separate files):

Architecture overview (keep brief in README)
Link to CONTRIBUTING.md for dev setup, testing, PR guidelines
Link to ARCHITECTURE.md for deep technical docs

Never put contributor-focused content above user-focused content.

Step 11: Banners and Visual Polish

When to create a banner:

Projects that have a clear visual identity (logo, mascot, color scheme)
Projects targeting a wide audience (not internal tools)
Projects that would benefit from "product" perception

Banner guidelines:

Width: 600-800px, centered
Keep it simple: project name + optional tagline + logo/icon
Use the project's color scheme if one exists
ASCII art banners are acceptable for terminal-focused tools but must render correctly in GitHub's markdown renderer -- always test by viewing the raw README on GitHub
If using ASCII art, wrap in a code block and center it. Test at different viewport widths.

Other visual polish:

Use <div align="center"> for centering images and badge rows
Add a thin horizontal rule (---) between major sections for visual breathing room
Use collapsible sections (<details>) for long reference content
For multi-screenshot sections, consider a 2-column grid:

<div align="center">
  <img src="assets/screenshots/feature-a.png" width="48%">
  &nbsp;
  <img src="assets/screenshots/feature-b.png" width="48%">
</div>

Step 12: Final Polish Checklist

Before finishing, verify:

Step 13: SEO and Discoverability

GitHub READMEs are indexed by Google and surface in GitHub search. Write with discoverability in mind.

Title and description:

The h1 title and the first paragraph are the most important for search engines
Include the primary use case in plain language: "pixel art cleanup tool" not just "normalize-pixelart"
The one-line description should contain words someone would actually search for
Good: "A command-line tool for cleaning up AI-generated pixel art into crisp, game-ready sprites"
Bad: "An implementation of grid-based raster normalization with OKLAB quantization"

Heading structure:

Use h2 (##) for major sections, h3 (###) for subsections -- search engines use heading hierarchy
Include keywords naturally in headings: "## Installation" is fine, but "## Installing on macOS, Linux, and Windows" is more searchable
Don't skip heading levels (h1 -> h3) -- this hurts both SEO and accessibility

Keyword placement:

Mention the project name and what it does in the first 160 characters (this becomes the Google snippet)
Include alternative terms people might search for. If your tool does "color quantization," also mention "palette reduction" or "color reduction"
Use natural language -- don't keyword-stuff

GitHub-specific discoverability:

The repo description (shown in search results and the repo header) should match the README's one-liner. Sync with: gh repo edit --description "your description"
Add relevant topics/tags to the repo: gh repo edit --add-topic pixel-art --add-topic gamedev --add-topic cli
Topics directly influence GitHub search ranking and the Explore page

Alt text on images:

Every image should have descriptive alt text -- this is indexed by search engines and critical for accessibility
Good: alt="PixFix desktop app showing before and after pixel art cleanup"
Bad: alt="screenshot" or empty alt

Common Issues

Screenshots not appearing

Check .gitignore -- image folders are often gitignored by default
Verify the relative path from the README to the image file
GitHub has a 25MB file size limit; optimize large screenshots

README feels too long

Move detailed reference content to docs/ and link to it
Use collapsible <details> sections for optional content
Cut ruthlessly: if a section doesn't help someone use or evaluate the project, remove it

README feels too "developer-y"

Lead with outcomes, not implementation details
Replace technical jargon with plain language in the description and features
Add screenshots -- visuals immediately make it feel more like a product
Move architecture/internals to a separate document

ASCII art banner looks broken

Test in GitHub's markdown renderer, not just your local editor
Wrap in triple backticks (code block) to preserve spacing
Some unicode characters render differently across platforms -- stick to basic ASCII
Center with <div align="center"><pre> if needed

Examples

Example 1: User asks to "write a README" for a new CLI tool

Actions:

Read the main source files to understand what the tool does
Check for any existing screenshots or assets
Write the README following the section order above
Flag any missing screenshots the user should capture
Verify all install/usage commands work

Result: Complete README.md with proper structure, badges, and TODO comments for screenshots

Example 2: User asks to "productize" an existing README

Actions:

Read the existing README
Identify what's missing vs. the structure template
Reorganize sections to match the priority order
Add banner/badges if missing
Rewrite description to focus on outcomes
Add screenshot sections (or TODOs if screenshots don't exist)
Move developer-focused content below user-focused content

Result: Restructured README that feels like a product landing page

Example 3: User asks to "add screenshots to the README"

Actions:

Look for existing screenshots in the repo (assets/, screenshots/, .github/)
If found: rename to descriptive names, add to README with proper formatting
If not found: tell user to capture with Xnapper and suggest specific shots to take
Place hero screenshot after badges, workflow screenshots in Usage section
Verify screenshots aren't gitignored

Result: README with properly formatted, well-placed screenshots

lovelaced/SKILL.md

Select an option

No results found

Select an option

No results found

Product README

Writing Tone

Instructions

Step 1: Audit the Project

Step 2: Determine the README Structure

Step 3: Write the Header Block

Step 4: Hero Visual

Step 4b: Demo GIFs and Videos

Step 5: Features Section

Step 6: Quick Start / Installation

Run

Step 7: Usage Section

Batch Processing

Step 9: Architecture / How It Works (Optional)

Step 10: Audience Prioritization

Step 11: Banners and Visual Polish

Step 12: Final Polish Checklist

Step 13: SEO and Discoverability

Common Issues

Screenshots not appearing

README feels too long

README feels too "developer-y"

ASCII art banner looks broken

Examples

Example 1: User asks to "write a README" for a new CLI tool

Example 2: User asks to "productize" an existing README

Example 3: User asks to "add screenshots to the README"