Concise README

Writes short, human-legible READMEs that lead with a quick start and surface the manual steps the human still needs to do. Use when creating or updating a README.

Run it as a prompt

Paste this into any AI agent, or fetch it: curl -s https://uplift.page/api/v1/prompts/concise-readme/raw

prompt.md

# Concise README

READMEs are read by humans in a hurry, not by agents. Write them to be skimmed in
under a minute: what this is, how to run it, and what still needs a human hand.

## When to use

- Creating a README for a new project, package, or directory
- Updating a README after finishing work (especially work that added setup steps)
- Reviewing a README that has grown long, stale, or machine-generated in tone

## Rules

1. **Open with a short, creative ASCII-art banner** — 3–6 lines, themed to the
   project (its name, mascot, or what it does), inside a code block so it renders
   monospaced. Make a new one per project; never reuse a generic banner.
2. After the banner, give the project name and **one plain sentence** saying what it
   is and why it exists. No taglines, no marketing.
3. Target **under 60 lines**. If a section needs more, link out to a doc instead of
   inlining it.
4. **Quick start before everything else**: the minimal copy-pasteable commands to get
   it running. If a command needs a placeholder, show the placeholder, not prose.
5. **Always include a "Still to do" section** listing what a human must still handle:
   - secrets / env vars to set, and where to get them
   - accounts, dashboards, or third-party settings to configure
   - manual or irreversible steps no script performs
   - open decisions waiting on a person
   If nothing remains, say so explicitly: "Nothing — clone and run."
6. Write in full sentences a non-author can follow; expand abbreviations and internal
   codenames on first use.
7. When finishing any work that adds a manual step, update "Still to do" **in the same
   change** — a stale TODO section is worse than none.

## Leave out

- Badge walls, changelogs, contributor ceremony, license boilerplate (one line max)
- Exhaustive config/API references — link to them
- Auto-generated directory trees and architecture essays
- Anything restating what the code or `--help` already says

## Skeleton

```markdown
# project-name

    (\(\        rabbit-cache
    ( -.-)      fast, forgetful, multiplies your reads
    o_(")(")

One sentence: what this is and why it exists.

## Quick start

    <the 2–5 commands that actually get it running>

Install it as a skill

Agents that support the Agent Skills standard load it automatically when it applies.

download

curl -fsSL https://uplift.page/p/concise-readme/SKILL.md --create-dirs -o .agents/skills/concise-readme/SKILL.md

or from any MCP client

MCP server: https://uplift.page/mcp
Tool: pull_skill  {"slug": "concise-readme"}

The full skill

READMEs are read by humans in a hurry, not by agents. Write them to be skimmed in under a minute: what this is, how to run it, and what still needs a human hand.

When to use

Creating a README for a new project, package, or directory
Updating a README after finishing work (especially work that added setup steps)
Reviewing a README that has grown long, stale, or machine-generated in tone

Rules

Open with a short, creative ASCII-art banner — 3–6 lines, themed to the project (its name, mascot, or what it does), inside a code block so it renders monospaced. Make a new one per project; never reuse a generic banner.
After the banner, give the project name and one plain sentence saying what it is and why it exists. No taglines, no marketing.
Target under 60 lines. If a section needs more, link out to a doc instead of inlining it.
Quick start before everything else: the minimal copy-pasteable commands to get it running. If a command needs a placeholder, show the placeholder, not prose.
Always include a "Still to do" section listing what a human must still handle:
- secrets / env vars to set, and where to get them
- accounts, dashboards, or third-party settings to configure
- manual or irreversible steps no script performs
- open decisions waiting on a person If nothing remains, say so explicitly: "Nothing — clone and run."
Write in full sentences a non-author can follow; expand abbreviations and internal codenames on first use.
When finishing any work that adds a manual step, update "Still to do" in the same change — a stale TODO section is worse than none.

Leave out

Badge walls, changelogs, contributor ceremony, license boilerplate (one line max)
Exhaustive config/API references — link to them
Auto-generated directory trees and architecture essays
Anything restating what the code or --help already says

Skeleton

# project-name

    (\(\        rabbit-cache
    ( -.-)      fast, forgetful, multiplies your reads
    o_(")(")

One sentence: what this is and why it exists.

## Quick start

    <the 2–5 commands that actually get it running>

## Still to do

- [ ] Set `API_KEY` in `.env` (from https://example.com/dashboard)
- [ ] Point DNS at the new host

Good: "Set DATABASE_URL in .env — get it from the Supabase project settings."
Bad:  "Ensure all required environment variables are properly configured."
      — vague; the reader still doesn't know which vars or where to find values.

Served from the uplift.page library and refreshed within 5 minutes of every update.