hallmark-readme

Overview

Write a README that doesn't read like it was generated by an LLM. Most AI-written READMEs share the same tells: generic headings, filler phrases, invented metrics, templated structure, no voice. This skill encodes the rules that produce READMEs which sound like a person wrote them.

When to Use

• The user asks for a README for their project.
• The user wants to improve an existing README that reads as AI-generated.
• The user says "write a readme", "make my readme better", or "this readme sounds like AI wrote it".
• Any time you're about to write a README — default to this skill.

Rules

1. No filler phrases

Banned words and phrases (never use these):

2. No invented metrics

Never fabricate numbers. If the user didn't supply a metric, don't invent one.

If a section needs a metric and you don't have one, use a different structure. A feature list doesn't need a metric. A comparison table doesn't need a metric. Skip it.

3. No templated structure

AI READMEs all follow the same shape: Title → Badges → Tagline → Features → Installation → Usage → Contributing → License. Break this pattern.

Real READMEs vary:

• A CLI tool README leads with installation and a one-line example, not features.
• A library README leads with the problem it solves, not badges.
• A skill README leads with what the agent + skill delivers, not a tagline.
• A small project README can be 20 lines. Don't pad it to 200.

4. Honest about limitations

Name what the project doesn't do. This is the single most reliable signal that a human wrote the README — LLMs avoid limitations.

5. Real structure, not generic headings

6. Voice

Write in first person or direct second person. Not corporate third person.

7. Examples are concrete

Every README must have at least one concrete, runnable example. Not a placeholder. Not a "TODO: add example". A real command or code block the reader can copy and run.

8. No badge spam

Badges are fine in moderation. AI READMEs pile on 8-12 badges (CI, coverage, npm, downloads, stars, license, contributions welcome, good-first-issues, Discord, Twitter). Use at most 3, and only if they carry real information:

• License badge: yes (MIT/Apache/etc.)
• CI badge: yes (if CI exists and passes)
• Version badge: yes (if published to a registry)
• Everything else: skip unless it adds real signal

Workflow

Step 1: Read the project

Before writing anything, read:

• The project's package.json, pyproject.toml, or equivalent (name, description, dependencies)
• The source code's entry point (what does it actually do?)
• Any existing README (what needs fixing?)
• The license file

Step 2: Identify the audience

Who reads this README? A stranger on GitHub. They have 10 seconds to decide if this project is worth their time. The first 3 lines must tell them what it does and whether it's relevant.

Step 3: Write the first 3 lines

Title (the project name). One-sentence description (what it does, not what it is). One-sentence "who is this for" or "what you get".

# tailscale-deploy

Deploy a service on your Tailscale tailnet so it's privately accessible from any of your devices.

## What it does

The agent deploys a web service onto your Tailscale tailnet. The service becomes reachable
from your laptop, phone, and any other device on your tailnet. No public exposure, no port
forwarding, no cloud relay.

Step 4: Add install + one example

Install instructions. One concrete example. These go near the top — not buried after features.

Step 5: Add the rest

Only add sections that carry real information:

• What it does (2-3 sentences)
• Install (code block)
• How to use (concrete example)
• Prerequisites (if any)
• What you get (table or list, if useful)
• Limitations (always — what doesn't it do?)
• License

Skip sections that would be empty or filler. A README with 5 useful sections is better than one with 10 sections where 5 are filler.

Step 6: Run the slop check

Read the README aloud. If any sentence sounds like it could appear in any other project's README, rewrite it. If any section could be deleted without losing information, delete it.

Common Pitfalls

1. Leading with badges, not content. Badges are decorative. The first thing the reader sees should be what the project does, not a row of SVG badges.
2. Describing what it is, not what it does. "A Python library for..." tells the reader nothing. "You get a running service on your tailnet" tells them what they get.
3. Overlong READMEs. A README is not documentation. Link to docs for deep content. Keep the README scannable in under 2 minutes.
4. No example. A README without a runnable example forces the reader to read the source to understand the project. Always include one.
5. Invented limitations. Don't write "None known" in the limitations section. If you can't name a real limitation, you don't understand the project well enough to write the README.

Verification Checklist

• No banned filler words (empower, seamless, leverage, robust, cutting-edge, comprehensive, powerful) appear anywhere in the README
• Every number or metric in the README was supplied by the user or is independently verifiable — none invented
• At least one concrete, runnable example (real command or code, not a placeholder) is present
• A "Limitations" or equivalent section names at least one real limitation
• The structure isn't the generic Title → Badges → Tagline → Features → Installation → Usage → Contributing → License template
• Read aloud: no sentence could be copy-pasted unchanged into another project's README