Apache License
Version 2.0, January 2004
https://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions.

"License" shall mean the terms and conditions for use, reproduction, and
distribution as defined by Sections 1 through 9 of this document.

"Licensor" shall mean the copyright owner or entity authorized by the
copyright owner that is granting the License.

"Legal Entity" shall mean the union of the acting entity and all other
entities that control, are controlled by, or are under common control with
that entity. For the purposes of this definition, "control" means (i) the
power, direct or indirect, to cause the direction or management of such
entity, whether by contract or otherwise, or (ii) ownership of fifty percent
(50%) or more of the outstanding shares, or (iii) beneficial ownership of
such entity.

"You" (or "Your") shall mean an individual or Legal Entity exercising
permissions granted by this License.

"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation source, and
configuration files.

"Object" form shall mean any form resulting from mechanical transformation or
translation of a Source form, including but not limited to compiled object
code, generated documentation, and conversions to other media types.

"Work" shall mean the work of authorship, whether in Source or Object form,
made available under the License, as indicated by a copyright notice that is
included in or attached to the work (an example is provided in the Appendix
below).

"Derivative Works" shall mean any work, whether in Source or Object form,
that is based on (or derived from) the Work and for which the editorial
revisions, annotations, elaborations, or other modifications represent, as a
whole, an original work of authorship. For the purposes of this License,
Derivative Works shall not include works that remain separable from, or
merely link (or bind by name) to the interfaces of, the Work and Derivative
Works thereof.

"Contribution" shall mean any work of authorship, including the original
version of the Work and any modifications or additions to that Work or
Derivative Works thereof, that is intentionally submitted to Licensor for
inclusion in the Work by the copyright owner or by an individual or Legal
Entity authorized to submit on behalf of the copyright owner. For the
purposes of this definition, "submitted" means any form of electronic, verbal,
or written communication sent to the Licensor or its representatives,
including but not limited to communication on electronic mailing lists, source
code control systems, and issue tracking systems that are managed by, or on
behalf of, the Licensor for the purpose of discussing and improving the Work,
but excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."

"Contributor" shall mean Licensor and any individual or Legal Entity on
behalf of whom a Contribution has been received by Licensor and subsequently
incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of this
License, each Contributor hereby grants to You a perpetual, worldwide,
non-exclusive, no-charge, royalty-free, irrevocable copyright license to
reproduce, prepare Derivative Works of, publicly display, publicly perform,
sublicense, and distribute the Work and such Derivative Works in Source or
Object form.

3. Grant of Patent License. Subject to the terms and conditions of this
License, each Contributor hereby grants to You a perpetual, worldwide,
non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
section) patent license to make, have made, use, offer to sell, sell, import,
and otherwise transfer the Work, where such license applies only to those
patent claims licensable by such Contributor that are necessarily infringed by
their Contribution(s) alone or by combination of their Contribution(s) with
the Work to which such Contribution(s) was submitted. If You institute patent
litigation against any entity (including a cross-claim or counterclaim in a
lawsuit) alleging that the Work or a Contribution incorporated within the Work
constitutes direct or contributory patent infringement, then any patent
licenses granted to You under this License for that Work shall terminate as of
the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the Work or
Derivative Works thereof in any medium, with or without modifications, and in
Source or Object form, provided that You meet the following conditions:

(a) You must give any other recipients of the Work or Derivative Works a copy
of this License; and

(b) You must cause any modified files to carry prominent notices stating that
You changed the files; and

(c) You must retain, in the Source form of any Derivative Works that You
distribute, all copyright, patent, trademark, and attribution notices from
the Source form of the Work, excluding those notices that do not pertain to
any part of the Derivative Works; and

(d) If the Work includes a "NOTICE" text file as part of its distribution,
then any Derivative Works that You distribute must include a readable copy of
the attribution notices contained within such NOTICE file, excluding those
notices that do not pertain to any part of the Derivative Works, in at least
one of the following places: within a NOTICE text file distributed as part of
the Derivative Works; within the Source form or documentation, if provided
along with the Derivative Works; or, within a display generated by the
Derivative Works, if and wherever such third-party notices normally appear.
The contents of the NOTICE file are for informational purposes only and do not
modify the License. You may add Your own attribution notices within Derivative
Works that You distribute, alongside or as an addendum to the NOTICE text from
the Work, provided that such additional attribution notices cannot be
construed as modifying the License.

You may add Your own copyright statement to Your modifications and may provide
additional or different license terms and conditions for use, reproduction, or
distribution of Your modifications, or for any such Derivative Works as a
whole, provided Your use, reproduction, and distribution of the Work otherwise
complies with the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise, any
Contribution intentionally submitted for inclusion in the Work by You to the
Licensor shall be under the terms and conditions of this License, without any
additional terms or conditions. Notwithstanding the above, nothing herein
shall supersede or modify the terms of any separate license agreement you may
have executed with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade names,
trademarks, service marks, or product names of the Licensor, except as
required for reasonable and customary use in describing the origin of the Work
and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
writing, Licensor provides the Work (and each Contributor provides its
Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied, including, without limitation, any warranties
or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any risks
associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory, whether in
tort (including negligence), contract, or otherwise, unless required by
applicable law (such as deliberate and grossly negligent acts) or agreed to in
writing, shall any Contributor be liable to You for damages, including any
direct, indirect, special, incidental, or consequential damages of any
character arising as a result of this License or out of the use or inability to
use the Work (including but not limited to damages for loss of goodwill, work
stoppage, computer failure or malfunction, or any and all other commercial
damages or losses), even if such Contributor has been advised of the
possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing the Work
or Derivative Works thereof, You may choose to offer, and charge a fee for,
acceptance of support, warranty, indemnity, or other liability obligations
and/or rights consistent with this License. However, in accepting such
obligations, You may act only on Your own behalf and on Your sole
responsibility, not on behalf of any other Contributor, and only if You agree
to indemnify, defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason of your
accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

---
name: standard-readme
description: Writes or audits READMEs against the Standard Readme spec. Use whenever the user asks to create, rewrite, improve, audit, or fix a README, or asks about README quality or structure - even if they never mention "standard readme".
metadata:
  version: "0.1.5"
  categories: "knowledge, development"
  topics: "readme, documentation, standard-readme, markdown, open-source"
  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:

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

```markdown
![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.

```markdown
[![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.

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

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

````markdown
## 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 are responsible, not everyone with commit access.

#### Thanks (optional)

H2 heading (`## Thanks`, `## Credits`, or `## Acknowledgements`). Recognize significant contributions, inspirations, or dependencies.

#### Contributing (required)

H2 heading. Must state:
1. Where to ask questions (issues, discussions, Discord, etc.)
2. Whether PRs are accepted
3. Any requirements (e.g., signing commits, running tests first)

```markdown
## Contributing

Feel free to open an issue or submit a PR. Bug reports and feature requests are welcome.

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
```

Link to a CONTRIBUTING.md if one exists. Link to the Code of Conduct if one exists.

#### License (required, always last)

H2 heading. Must be the final section. State the license name (or SPDX identifier), the copyright holder, and link to the LICENSE file.

```markdown
## License

[MIT](LICENSE) (c) 2024 Jane Smith
```

Use `UNLICENSED` if no license. Use `SEE LICENSE IN <filename>` for complex/multi-license situations.

---

## Write Mode Workflow

When creating or rewriting a README:

1. **Gather context** - Read the project's existing files to understand what it is: package.json/Cargo.toml/pyproject.toml (name, description, dependencies), existing README, LICENSE, CONTRIBUTING.md, source code structure, CI config. Don't ask the user for information you can derive from the codebase.

2. **Determine relevant sections** - Start with the required sections. Add optional sections only when the project justifies them:
   - Banner: only if an image already exists in the repo
   - Badges: if CI, package registry, or other status indicators are set up
   - Long Description: if the short description can't convey the purpose alone
   - Table of Contents: if the final README will exceed 100 lines
   - Security: only for security-sensitive projects
   - Background: if the project has non-obvious motivation or history
   - API: if the project exports functions/classes for programmatic use
   - Maintainers: if the project has identified maintainers
   - Thanks: if there are notable acknowledgements
   - Extra Sections: for project-specific content (config, architecture, deployment) that genuinely helps users

3. **Write the README** - Follow the section order exactly. Make sure:
   - Short description is under 120 characters
   - Install and Usage both have code blocks
   - Code examples actually work (match the project's real API/CLI)
   - No broken internal links
   - License matches the actual LICENSE file
   - ToC links match all H2 sections (if ToC is included)

4. **Self-check** - Before presenting the result, verify the section order matches the spec, all required sections are present, and no empty sections were added just for completeness.

---

## Audit Mode Workflow

When checking an existing README:

1. **Read the README** and identify each section by heading and position.

2. **Check against the spec**, reporting:
   - Missing required sections
   - Sections in wrong order
   - Short description over 120 characters or formatted as blockquote
   - Install/Usage missing code blocks
   - License not being the last section
   - Broken internal links (anchors that don't match headings)
   - ToC missing or incomplete (if README >100 lines)
   - Banner referencing an external URL instead of a local image

3. **Present findings** as a numbered list, grouped by severity:
   - **Must fix**: violations of required rules
   - **Should fix**: violations of optional-but-recommended rules
   - **Suggestions**: improvements that would strengthen the README

4. **Offer to fix** - After presenting the audit, ask if the user wants you to rewrite the README to fix the issues.

---

## Things to Avoid

- Don't add empty sections. If Background has nothing to say, omit it.
- Don't invent package names or CLI commands. Derive them from the actual project files.
- Don't use blockquote (`>`) for the short description.
- Don't place License anywhere except last.
- Don't add a ToC to READMEs under 100 lines unless the user specifically asks.
- Don't include the Title or ToC heading in the Table of Contents links.
- Don't use external URLs for the banner image.