/standard-readme

name: standard-readme
description: >
  Write or audit README files following the Standard Readme specification
  (github.com/RichardLitt/standard-readme). Use this skill whenever the user asks
  to create, write, rewrite, improve, audit, or fix a README - even if they don't
  mention "standard readme" explicitly. Also trigger when the user says "add a
  README", "write docs for this repo", "check my README", or anything about README
  quality or structure.
metadata:
  version: "0.1.2"
  openclaw:
    homepage: https://github.com/tenequm/skills/tree/main/skills/standard-readme
    emoji: "📖"

Standard Readme

Generate and audit README.md files that comply with the [Standard Readme](https://github.com/RichardLitt/standard-readme) specification.

Two Modes

**Write mode** (default): Generate a new README or rewrite an existing one. **Audit mode**: When the user asks to "check", "audit", "review", or "lint" a README, analyze it against the spec and report issues without rewriting.

---

The Specification

A compliant README has sections in this exact order. Some are required, some optional. Optional sections should be included only when they add real value for the project - don't pad the README with empty sections.

Section Order

1.  Title                    REQUIRED   (H1)
2.  Banner                   optional   (image, no heading)
3.  Badges                   optional   (no heading)
4.  Short Description        REQUIRED   (plain text, no heading)
5.  Long Description         optional   (no heading)
6.  Table of Contents        REQUIRED*  (H2)
7.  Security                 optional   (H2)
8.  Background               optional   (H2)
9.  Install                  REQUIRED** (H2)
10. Usage                    REQUIRED** (H2)
11. [Extra Sections]         optional   (H2, custom titles)
12. API                      optional   (H2)
13. Maintainer(s)            optional   (H2)
14. Thanks / Credits         optional   (H2)
15. Contributing             REQUIRED   (H2)
16. License                  REQUIRED   (H2, always last)

`*` Table of Contents is only required when the README exceeds 100 lines (excluding the ToC itself). `**` Install and Usage are optional for documentation-only repositories (no functional code).

Section Rules

Title (required)

H1 heading. Must match the repository/package name. If using a different display title, include the repo name in italics and parentheses:

# My Awesome Project _(my-awesome-project)_

Banner (optional)

Image placed directly after the title, no heading. Must reference a local image in the repository, not an external URL.

![banner](assets/banner.png)

Include only if the project actually has a banner image.

Badges (optional)

One badge per line, directly after banner (or title if no banner). No heading.

[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
[![npm version](https://img.shields.io/npm/v/my-package.svg?style=flat-square)](https://npmjs.org/package/my-package)

Include when the project uses CI, has a published package, or benefits from status indicators. Always include the Standard Readme compliance badge.

Short Description (required)

A single line of plain text, under 120 characters. No heading, no blockquote (`>`). Must match the description in the package manager and GitHub repo settings.

A CLI tool that converts Markdown files to PDF with custom styling.

Long Description (optional)

One or more paragraphs after the short description. No heading. Use this to explain motivation, goals, or context that doesn't fit in 120 characters. If the title doesn't match the repo/package name, explain why here.

Table of Contents (required if >100 lines)

H2 heading. Links to every subsequent section. Does not include the title or the ToC itself. At minimum, list all H2 headings; optionally include H3/H4.

## Table of Contents

- [Install](#install)
- [Usage](#usage)
- [API](#api)
- [Contributing](#contributing)
- [License](#license)

Security (optional)

H2 heading. Include only if the project has security considerations important enough to highlight before install/usage (cryptographic software, auth libraries, tools handling secrets). Otherwise, put security notes in an Extra Section or omit.

Background (optional)

H2 heading. Motivation, history, intellectual context. A `### See Also` subsection fits here.

Install (required)

H2 heading. Must contain a code block showing how to install.

## Install

```sh
npm install my-package

Add a `### Dependencies` subsection if there are unusual or manual dependencies. Consider an `### Updating` subsection for projects where upgrades need special steps.

#### Usage (required)

H2 heading. Must contain a code block showing common usage.

- CLI tool: show the command and typical flags
- Library: show import + basic usage
- Both: include a `### CLI` subsection

```markdown
## Usage

```js
import { convert } from 'my-package'

const pdf = await convert('README.md', { style: 'github' })

#### Extra Sections (optional)

Zero or more custom H2 sections between Usage and API. Use descriptive titles relevant to the project (e.g., "Architecture", "Configuration", "Deployment"). This is the right place for project-specific content that doesn't fit the standard sections.

#### API (optional)

H2 heading. Document exported functions, classes, types. Include signatures, return types, and notable caveats. For large APIs, point to a separate `API.md`.

Include when the project exports a programmatic API that users call directly.

#### Maintainer(s) (optional)

H2 heading (`## Maintainer` or `## Maintainers`). List project maintainers with at least one contact method (GitHub profile link or email). Keep this small - people who a