readme-writer

Write a clear, well-structured README for a software project or open-source repo. Use when asked to write or improve a README, document a project, or make a repo approachable. Produces a complete README — one-line pitch, badges, quickstart, usage, install, contributing, license — that gets someone from landing to running fast.

Published by mohitagw15856 ↗mohitagw15856/pm-claude-skills

Try your first task

readme-writer

Start a fresh conversation. Replace the highlighted placeholders.

Use readme-writer to write a complete README.md for [project name] using [purpose and target audience] and [install command plus minimal working example], accurately reflecting its features, status, license, and contribution guidance.

Required inputs

[project name]
[purpose and target audience]
[install command plus minimal working example]

User-approved starter prompt based on a pinned source version; check current skill requirements before running. Task evidence ↗

SKILL.md

name: readme-writerdescription: "Write a clear, well-structured README for a software project or open-source repo. Use when asked to write or improve a README, document a project, or make a repo approachable. Produces a complete README — one-line pitch, badges, quickstart, usage, install, contributing, license — that gets someone from landing to running fast."

README Writer Skill

The README is a project's front door — most people decide in seconds whether to use or bounce. This skill writes a clear, scannable README that answers what is this, why should I care, how do I run it immediately, then layers in the detail. Structured so a newcomer gets to a working result fast.

Not quite this? Use readme-benefit-writer when you already have a README and want each feature rewritten as a user benefit.

Required Inputs

Ask for these only if they aren't already provided:

Project name & one-line purpose — what it is and what problem it solves.
Who it's for — the target user/developer.
Install & basic usage — how to install and the simplest working example.
Key features / differentiators — the few things that matter most.
Project facts (optional) — language, license, links (docs, demo), contribution policy, status (alpha/stable).

Output Format

A complete README.md:

[Project name]

One-line pitch — what it does and for whom.

(Badges line — build, version, license — as placeholders to fill.)

Why [project]? — 2–3 sentences or bullets: the problem and what makes this worth using (honest, specific).

Features — the handful that matter, as a tight bullet list.

Quickstart

# install
# minimal working example

…with the expected result shown.

Usage — the common cases, with short code examples. Link out to full docs rather than inlining everything.

Installation — fuller install/requirements if the quickstart was minimal.

Contributing — how to contribute / link to CONTRIBUTING; be welcoming.

License — the license line.

(Adapt sections to the project; omit what doesn't apply. Keep it scannable with clear headings.)

Quality Checks

Opens with a one-line pitch that says what it is and for whom
A newcomer can copy-paste the quickstart to a working result
"Why this" is specific and honest, not generic praise
Scannable structure (headings, short sections); deep detail is linked, not dumped
Install, usage, contributing, and license are all covered (or consciously omitted)

Anti-Patterns

Do not bury what-it-does under a wall of badges or backstory — pitch first
Do not write a quickstart with missing steps — it must actually run
Do not inline the entire documentation — summarize and link
Do not over-promise; reflect the real project status (alpha/beta/stable)
Do not skip the license — it determines whether anyone can legally use it

Based On

Open-source README best practices (one-line pitch, time-to-first-success quickstart, scannable structure, standard sections).

Example Trigger Phrases

"Improve a README."
"Document a project."
"Make a repo approachable."