{
  "skill_name": "readme-creator",
  "evals": [
    {
      "id": 1,
      "prompt": "Rewrite a hosted web app README. The only consumer entry is https://app.example.test; package.json is private and there is no supported self-hosting mode.",
      "expected_output": "Lead with the hosted entry rather than inventing package installation.",
      "files": [],
      "assertions": [
        "Omits npm install for the private app",
        "Does not add registry version badges",
        "Preserves a concise consumer-focused structure"
      ]
    },
    {
      "id": 2,
      "prompt": "Rewrite a published CLI README. The package name is @acme/harbor and its output includes a toolbar example.",
      "expected_output": "Use the actual package name without treating substrings foo or bar as boilerplate.",
      "files": [],
      "assertions": [
        "Keeps @acme/harbor intact",
        "Does not flag toolbar merely for containing bar",
        "Checks CLI examples against the documented interface"
      ]
    }
  ],
  "routing": {
    "should_trigger": [
      "Rewrite a hosted web app README. The only consumer entry is https://app.example.test; package.json is private and there is no supported self-hosting mode.",
      "Rewrite a published CLI README. The package name is @acme/harbor and its output includes a toolbar example."
    ],
    "near_miss": [
      {
        "prompt": "Fix the stale commands in AGENTS.md.",
        "expected": "agents-md"
      }
    ]
  }
}

# Badges and Shields

Markup and placement for badges. Phase 4 of SKILL.md decides whether this project gets badges at all; this file assumes Phase 1 found a registry listing.

One placement, one colour scheme, two badges. The point of the constraint is that a set of repos should look like one set of repos.

## Placement

The `<p align="center">` row inside the header block from `section-templates.md`, below the tagline and second line:

```markdown
<p align="center">
  <a href="{{registry-url}}">
    <img src="{{version-badge}}" />
  </a>
  <a href="https://github.com/{{owner}}/{{repo}}/blob/main/LICENSE.md">
    <img src="https://img.shields.io/github/license/{{owner}}/{{repo}}?style=flat&labelColor=000000&color=000000" />
  </a>
</p>
```

Blank line before and after the `<p>` row: the block is HTML until the next blank line, and the `</div>` that follows needs its own.

## Colour scheme

Every badge carries `?style=flat&labelColor=000000&color=000000`. `labelColor` paints the left half, `color` the right, so both go black and the badge reads as one solid chip.

- `style`, `color`, `labelColor`, `logo`, and `logoColor` are the query parameters shields.io documents. `colorA` and `colorB` are older aliases that still render identically; leave them alone in repos that already use them, and write the documented names in new ones.
- `flat` is the shields default, so `style=flat` is redundant. Keep it anyway: the point of the query string is that every badge URL in a set is byte-for-byte the same shape.
- A black version badge no longer signals freshness by colour, which is the point. It is a link to the registry, not a status light.
- Shields' own defaults (blue, yellow, green, brightgreen) and the `for-the-badge` and `flat-square` styles are what drift looks like. If one repo in a set uses them, the set looks unmaintained.

## Version badge by registry

```markdown
<!-- npm -->
https://img.shields.io/npm/v/{{name}}?style=flat&labelColor=000000&color=000000
<!-- link to -->  https://www.npmjs.com/package/{{name}}

<!-- crates.io -->
https://img.shields.io/crates/v/{{name}}?style=flat&labelColor=000000&color=000000
<!-- link to -->  https://crates.io/crates/{{name}}

<!-- PyPI -->
https://img.shields.io/pypi/v/{{name}}?style=flat&labelColor=000000&color=000000
<!-- link to -->  https://pypi.org/project/{{name}}/

<!-- VS Code Marketplace -->
https://img.shields.io/visual-studio-marketplace/v/{{publisher}}.{{ext}}?style=flat&labelColor=000000&color=000000
<!-- link to -->  https://marketplace.visualstudio.com/items?itemName={{publisher}}.{{ext}}
```

For a monorepo publishing one package from a subdirectory, the badge uses the **published** package name from that package's manifest, not the private root name.

## Skill bundle: installs badge

A skill bundle has no version, but skills.sh is its registry and serves a shields endpoint with install counts. It already returns black-on-black `flat`, so no query string is needed beyond the label:

```markdown
<a href="https://www.skills.sh/{{owner}}/{{repo}}">
  <img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fwww.skills.sh%2Fapi%2Fbadge%2F{{owner}}%2F{{repo}}&label=installs" />
</a>
```

The `url` parameter is percent-encoded once; pasting the raw `https://www.skills.sh/api/badge/...` URL renders a shields error badge. Pair it with the license badge and stop.

## What does not earn a badge

| Badge | Why not |
|-------|---------|
| CI status | Renders as a permanent failure whenever the workflow does not fire on the default branch, and even when green tells the reader nothing they can act on. |
| Stars, forks, watchers | Decoration. The count is already on the page, immediately above. |
| Downloads per month | Fluctuates for reasons unrelated to the project, and a low number argues against you. |
| Runtime version (`node-20+`) | Duplicates the Requirements section in a second visual language. Put the version in prose where it can carry a reason. |
| "maintained: yes" | Hand-set, so it means nothing, and it goes stale in exactly the case where a reader would want it. |
| License, when the repo has no LICENSE file | The shields endpoint reads the repo's detected license. With no license file it renders `not identified`, which is worse than no badge. |

## Third badge

One case earns a third: a distribution channel a reader would otherwise not know exists, such as a VS Code Marketplace listing alongside the npm package, or a Homebrew tap. Add it as a distribution link, in the same black style, and stop there.

# README Quality Checklist

Use as a consumer-path and house-style rubric. Apply only relevant items; a hosted app with no installable product uses its live URL. If scoring is requested, exclude N/A items and keep editorial scores separate from executed verification.

## Audience (5 checks)

1. No section that only helps someone changing the code (Development, Tech Stack, Architecture, Release, Workspaces, Scripts, Contributing, Project structure)
2. Install is what a stranger runs, not `git clone` (unless cloning genuinely is the product)
3. The install command uses the published package name from the manifest, not the repo or private root name, and the package exists on the registry under that name
4. A first-time reader gets something running, or sees the thing working, within 60 seconds
5. Content moved out landed in `AGENTS.md` or `CONTRIBUTING.md` rather than being deleted

## Structure (7 checks)

6. Title is the display name, linked to the live site if one exists
7. Tagline directly below the title with no heading, and it does not open with the project's own name
8. A plain second line saying what you do with it
9. Applicable sections follow the spine: header, Demo, Install, Quickstart, capability sections, License; omit Install for browser-only consumption
10. Two to four capability sections, or a stated reason for a fifth
11. Headings use the canonical names: `Install`, `Quickstart`, `Demo`, `License`
12. Headings are sentence case, and nothing goes deeper than `###`

## Content (6 checks)

13. Every code block runs copy-pasted, no modification
14. No placeholder text, TODO markers, or `foo`/`bar`/`my-app`/`your-name-here` values
15. Quickstart produces visible output and is complete rather than elided
16. Install shows one command, not a package-manager matrix
17. Capability bullets use `- **Name:** what it does.` with a colon
18. Images are committed under `.github/assets/`, not hotlinked to an external host

## Rendering (4 checks)

19. Markdown inside `<div align="center">` and around `<p align="center">` is separated by blank lines
20. For a published package, every image `src` is an absolute `raw.githubusercontent.com` URL; for a GitHub-only repo, relative paths are fine
21. At most one `> [!NOTE]`-style alert, and none if the package publishes to PyPI
22. A dark/light logo uses `<picture>` with an `<img>` fallback, not `#gh-dark-mode-only` fragments

## Writing (6 checks)

23. Active voice ("Install the package" not "The package can be installed")
24. No "This project is..." or "This is a..." openers
25. No em dashes, and table cells meaning "not applicable" are empty rather than a dash
26. Consistent terminology (one term per concept, same casing)
27. No orphaned sections (every heading has content below it)
28. No hedged capability claims ("should work", "aims to", "tries to")

## Badges and footer (4 checks)

29. Badges present only if the project is listed on a registry (npm, crates.io, PyPI, VS Code Marketplace, skills.sh)
30. Two badges (version or installs, plus license) in one style and one colour scheme, or a third that names a distribution channel
31. No CI, stars, downloads, runtime-version, or "maintained" badge, and no license badge without a `LICENSE` file
32. License section present, with the footer credit line if the house style has one

## Freshness (4 checks)

33. Badge package name matches the published package (or badges are absent)
34. Spot-check 2-3 links are not broken
35. No references to deprecated APIs, removed features, or old package names
36. Length fits the type: most READMEs 40 to 90 lines, a CLI with flag tables up to 120, and anything past about 130 has its overflow linked out rather than inlined

## Project-Type Specific

### CLI tools
- Documented flags match the real `--help` output
- Examples show real commands, and the reader can tell what each produces

### Libraries
- Import paths match the package structure
- API detail beyond a screenful lives in a linked docs site, not inline

### Web apps
- Demo or screenshot is present, and above Quickstart
- Environment variables documented only if readers self-host

### Monorepos
- The README is written for what a stranger installs, not for the repo layout
- No workspaces table as the lede

### Skill bundles
- Install is the one `npx skills add` command, with the compatible agents named
- Every skill row links to its `SKILL.md`, and the count in the header matches the rows

## Automatic Fail

Any of these means the README is not ready:

- No description (reader cannot tell what the project does)
- No install or demo (reader can neither use it nor see it)
- Default boilerplate README (e.g., unchanged create-next-app template)
- Code examples that cannot run (syntax errors, missing imports, wrong API)
- A section that only serves contributors
- An install command against a package name that does not exist on the registry

# Section Templates

Markup for each section, plus which capability sections fit each project type. Phase 2 of SKILL.md fixes the five-section spine; this file supplies the skeletons and the per-type choices that go between Quickstart and License.

## Contents

- [The spine](#the-spine)
- [Capability sections](#capability-sections)
- [Per-type notes](#per-type-notes)
- [Sections that belong somewhere else](#sections-that-belong-somewhere-else)

## The spine

### Header block

One shape for every type. Registry-listed projects keep the badge row; everything else drops it. Keep every blank line shown: each HTML tag runs as raw HTML until the next blank line.

```markdown
<div align="center">

# {{Display Name}}

**{{tagline, 8 to 16 words, no full stop, inline links where an upstream project earns credit}}**

{{one plain sentence on what you actually do with it}}

<p align="center">
  <a href="{{registry-url}}"><img src="{{version-badge}}" /></a>
  <a href="{{license-url}}"><img src="{{license-badge}}" /></a>
</p>

</div>
```

Link the H1 to the live site when one exists: `# [{{Display Name}}]({{url}})`.

A logo replaces the H1 only when the wordmark is the brand. Use `<picture>` so it survives both GitHub themes, with the light version as the fallback (PyPI drops the `<source>` lines and shows only the `<img>`):

```markdown
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="{{image-base}}/logo-dark.svg">
  <img alt="{{Display Name}}" src="{{image-base}}/logo-light.svg" width="320">
</picture>
```

`{{image-base}}` is `.github/assets` for a GitHub-only repo and `https://raw.githubusercontent.com/{{owner}}/{{repo}}/main/.github/assets` for anything published to a registry.

### Demo

Only when a live URL exists. One line, then the button:

```markdown
## Demo

{{One line naming what the reader will see.}}

<p>
<a href="{{live-url}}">
<img alt="View demo" src="{{image-base}}/demo.svg" width="200" />
</a>
</p>
```

A plain link works too. The button is a house-style choice; check the ghostwriter `readme` profile for the asset.

A screenshot can stand in for a demo when there is nothing to interact with. Commit it under `.github/assets/`.

### Install

The single fastest path, one command:

```bash
npm install -g {{name}}      # CLI
npm install {{name}}         # library
```

Add one sentence under it only when the command has a consequence worth stating ("Run that inside any git repository", "Requires Node 20.11+").

No package-manager matrix, no `<details>` tabs. Anyone who prefers pnpm can translate `npm install`.

For an app with no install step, this section becomes the deploy or hosted link, or drops out entirely and Demo carries it.

### Quickstart

The shortest complete thing that produces visible output. Complete beats short: this is the one section that keeps its full length.

```markdown
## Quickstart

{{optional one-line setup, e.g. the HTML element the library mounts to}}

{{one code block, real values, runnable as pasted}}
```

For a CLI, that is two or three commands with a comment above each. For a library, one import plus one rendered result. For an app, the URL to open.

### License

```markdown
## License

{{MIT}}

---

{{footer credit line, if the house style has one}}
```

Bare licence name is the default. A licence that imposes real constraints keeps its real text: font licences, non-commercial upstreams, and anything the reader could get wrong need the sentence that explains the constraint.

## Capability sections

Two to four, between Quickstart and License. Named for what the reader gets, as a plain noun phrase.

| Section | Use it for | Shape |
|---------|-----------|-------|
| `## What you can do` | An app or tool whose value is a set of things you do | `- **Verb phrase:** what happens.` bullets |
| `## Modes` / `## Presets` | Distinct operating modes the reader picks between | one bullet per mode, with the parameters it exposes |
| `## Usage` | A library with two or three patterns beyond the Quickstart | one code block per pattern, simplest first |
| `## API` | A library or a CLI that also exports one | signature plus one-line description per public export |
| `## Options` | A CLI with more than three flags | table: Flag, Default, Description |
| `## Commands` | A CLI with subcommands | table: Command, Description |
| `## Keyboard shortcuts` | Anything with a UI | table: Key, Action |
| `## Configuration` | A config file or options object | table: Option, Type, Default, Description |
| `## Environment variables` | An app the reader self-hosts | table: Variable, Description, Required |
| `## Requirements` | A non-obvious runtime, OS, or hardware need | bullets, each with the reason |
| `## Notes` | The two or three awkward facts, plus credit to prior art | bullets |
| `## Theming` / `## Browser support` | Where it is the actual question readers have | whatever fits |

`## Notes` is the pressure valve. Three sections of one bullet each (Requirements, Caveats, Credits) read as padding; one `## Notes` with three bullets reads as honest.

Bullet form throughout: `- **Name:** what it does.` Table cells meaning "not applicable" are empty, not a dash.

A `> [!WARNING]` alert earns a place only for the one fact that breaks installs (a native dependency, a breaking major). It renders as a callout on GitHub, npm, and crates.io and as a literal `[!WARNING]` blockquote on PyPI, so a Python package states the fact in plain prose instead.

## Per-type notes

### CLI tool

- Install shows the global install; add `npx {{name}}@latest` above it when the tool is more often run than installed.
- `## Options` as a table beats a pasted `--help` dump, which goes stale silently and is unreadable on mobile.
- Document the flags a reader would not guess. `--help` already covers the rest, and a README documenting all thirty flags pushes Quickstart below the fold.
- Only add `## API` if the package genuinely exports one.

### Library / package

- Quickstart is install plus a minimal working example, under about 15 lines.
- Link an external docs site rather than growing an API section past a screenful.
- `## Notes` carries the platform requirements and the prior art. A library inspired by others should say so; it is also the fastest way for a reader to place it.
- Images use the `raw.githubusercontent.com` base: the same file renders on the repo page and the registry page.

### Web app

- No badges, no registry install. Demo is the most important section, and often the only one above Quickstart.
- `## Environment variables` matters only for an app readers self-host. For a hosted app nobody will run locally, skip it and skip Quickstart too; Demo plus capability sections is the whole README.
- A privacy or data-handling claim, where true, is worth its own two-sentence section. It is often the reader's real question.

### Framework

- Feature descriptions run longer here: explain the why with the what.
- Quickstart then one `## Usage` with the two or three core patterns. Push the configuration reference to a docs site rather than inlining a forty-row table.

### Monorepo

Write the README for what a stranger installs or visits, not for the repo layout. A repo whose `apps/cli` publishes to npm gets a CLI README at the root, with the published package name in the install command and the badge.

- No workspaces table. The layout is `AGENTS.md` content.
- If the repo genuinely ships several things a reader chooses between, that is a `## Packages` table of two to five rows, each linking to its own README, and it is a capability section rather than the lede.

### Skill bundle

The bundle's registry is skills.sh, which lists the skills with install counts and renders each `SKILL.md` on its own page; it does not show the README. So the README is read on GitHub, and its job is the install command plus a scannable catalogue.

- Header carries the skill count in the second line, the skills.sh installs badge, and the license badge (`badges-and-shields.md` has the endpoint).
- Install is the one `npx skills add {{owner}}/{{repo}}` command. Name the compatible agents in one line under it; where the command takes agent flags, state the flag shape once (`--agent` is space-separated, and a comma-separated list is rejected whole).
- One line linking the skills.sh listing, so readers can see install counts and browse per-skill pages.
- The `## Skills` table or list is the core content: one row per skill, name linked to its `SKILL.md`, then what it does in one clause. Group under `###` category headings once past about ten skills; this is the sanctioned use of `###`.
- No Quickstart: invoking a skill is the agent's job, and the per-skill pages show the body.

## Sections that belong somewhere else

The audience gate in Phase 2 rules these out. Move the content, do not delete it, and create the destination file when it does not exist.

| Section | Destination |
|---------|-------------|
| `## Development`, `## Scripts`, `## Common commands` | `AGENTS.md` or `CONTRIBUTING.md` |
| `## Workspaces`, `## Project structure`, `## Architecture` | `AGENTS.md` |
| `## Release`, `## Publishing` | `CONTRIBUTING.md` |
| `## Tech Stack` | nowhere; the reader can see the language on the repo sidebar |
| `## Contributing` | `CONTRIBUTING.md`, which GitHub links from the issue and PR composer |
| `## Roadmap` | GitHub issues or a project board, where it can stay current |
| `## Changelog` | `CHANGELOG.md` or GitHub releases |

`## Contributing` is the one worth arguing about. GitHub already links `CONTRIBUTING.md` from the issue and PR composer, so a README section repeating it costs a screenful and reaches nobody who was not already looking.