hallmark-readme

---
name: hallmark-readme
description: Use when a user asks for a project README, wants an existing README that reads as AI-generated fixed, or you are about to write a README for any project.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [readme, documentation, anti-ai-slop, writing]
    related_skills: [changelog-generator, skills-portfolio-scaffold, portfolio-upkeep]
---

# 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):

| Banned | Use instead |
|---|---|
| empower, empowering | (delete — the verb does the work) |
| seamless | (delete — nothing is seamless) |
| leverage | use |
| robust | (delete — show it with specifics) |
| cutting-edge, state-of-the-art | (delete — let the reader judge) |
| comprehensive | (delete — the structure shows comprehensiveness) |
| powerful | (delete — show power with specifics) |
| "built with love" | (delete) |
| "designed for developers" | (delete — who else would it be for?) |
| "in today's fast-paced world" | (delete — always) |

### 2. No invented metrics

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

| Wrong | Right |
|---|---|
| "Trusted by 50,000+ developers" | (omit — or use the real number if the user provided it) |
| "10x faster than alternatives" | (omit — or cite a real benchmark) |
| "Used by teams at Google, Meta, Stripe" | (omit — unless the user confirmed these) |
| "Increases productivity by 47%" | (omit — or cite the study) |

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.

| Wrong | Right |
|---|---|
| "Works with any framework" | "Works with React and Vue. Svelte support is planned." |
| "Production-ready" | "Used in production by the author. Not yet tested at scale." |
| (no limitations section) | A "Limitations" or "Known Issues" section with real items |

### 5. Real structure, not generic headings

| Generic (AI tell) | Specific (human signal) |
|---|---|
| ## Features | ## What it does |
| ## Getting Started | ## Install |
| ## Usage | ## How to use (with a concrete example) |
| ## Contributing | ## For contributors (only if the project accepts contributions) |
| ## FAQ | (only if there are actually frequently asked questions) |

### 6. Voice

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

| Wrong | Right |
|---|---|
| "This project enables developers to..." | "You get a running service on your tailnet." |
| "The tool provides functionality for..." | "The agent deploys your app and gives you a URL." |
| "It is recommended that users..." | "Run this before you start." |

### 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.

| Wrong | Right |
|---|---|
| `my-tool --input <file> --output <file>` | `my-tool --input data.csv --output cleaned.json` |
| "See the docs for usage examples" | A 5-line code block that does something real |
| "TODO: add example" | (write the example) |

### 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".

```markdown
# 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

# hallmark-readme



Write a README that doesn't sound like an LLM generated it.



## What it does



The agent reads your project and writes a README that follows anti-AI-slop rules: no filler phrases, no invented metrics, no templated structure, honest about limitations, concrete examples, real voice. The result reads like a human wrote it because it follows the patterns that distinguish human writing from LLM defaults.



## Install



```bash

hermes skills install https://raw.githubusercontent.com/THEROCKSSS/hermes-skills-portfolio/main/skills/hallmark-readme/SKILL.md

```



## How to use



```

"Write a README for my project"

```



The agent reads your project files, identifies the audience, and writes a README with:

- A one-sentence description of what it does (not what it is)

- Install instructions near the top

- One concrete, runnable example

- Real section headings (not generic "Features" / "Getting Started")

- A limitations section naming what the project doesn't do

- No filler, no invented metrics, no badge spam



## What it checks for



| AI tell | This skill |

|---|---|

| "empower", "seamless", "leverage", "robust" | Banned — deleted on sight |

| "Trusted by 50,000+ developers" | Never invented — omitted if no real number exists |

| Title → Badges → Features → Installation → Usage | Structure varies by project type, not templated |

| No limitations section | Always includes real limitations |

| "This project enables developers to..." | First person or direct second person, not corporate third |

| `my-tool --input <file>` | Concrete examples with real values, not placeholders |



## Example



**Before (AI-generated):**



```markdown

# Awesome Tool



A powerful, comprehensive tool that empowers developers to seamlessly leverage

cutting-edge features. Built with love. Trusted by 50,000+ teams worldwide.



## Features

- Robust architecture

- Seamless integration

- Comprehensive documentation

```



**After (hallmark-readme):**



```markdown

# 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.



## Install



  hermes skills install https://github.com/...



## Example



  User: "Deploy localhost:8080 on my tailnet"

  Agent: runs tailscale serve --https 8080

  Result: https://my-machine.tailnet.ts.net



## Limitations



- Requires Tailscale installed and authenticated on both the host and the accessing device.

- `tailscale serve` is tailnet-only; `tailscale funnel` exposes to the public internet.

```



The second one sounds like a person wrote it because it follows the rules: no filler, no invented numbers, real structure, concrete example, honest limitations.