القائمة
Use when creating or updating README.md files. Provides structure guidelines for libraries, applications, and monorepos, plus formatting rules and required sections.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | readme-authoring |
| description | Use when creating or updating README.md files. Provides structure guidelines for libraries, applications, and monorepos, plus formatting rules and required sections. |
This skill guides the creation and maintenance of README.md files. Before writing any README content, read the writing-clearly-and-concisely skill and apply its principles throughout.
Determine the project type first—it dictates structure:
| Type | Indicators |
|---|---|
| Application | Runnable binary, has bin field, Docker deployment, user-facing tool |
| Library | If it doesn't have a binary/executable, it's probably this |
| Monorepo | package.json contains workspaces, repo contains packages/ or plugins/ directory, multiple package.json files |
Start with an H1 containing the project name, followed immediately by a one-to-two sentence description:
# project-name
A brief description of what this project does and why someone would use it.
Place this section at the very bottom. Use the date command to get the current year:
date +%Y
Format:
## License
Copyright © YEAR [Author Name](https://github.com/username). Licensed under the [License Name](LICENSE)
For libraries, use this section order:
# library-name
One sentence describing the library.
## Example
[Show a compelling, copy-pasteable example immediately]
## Installation
[Package manager commands]
### Prerequisites
- Node.js >= X.Y
- Peer dependencies (if any)
## Usage
[Detailed usage with examples]
## Configuration
[If applicable]
## Development
[If ARCHITECTURE.md, DEVELOPMENT.md, or CONTRIBUTING.md exist]
## Acknowledgements
[If applicable - penultimate section]
## License
[Always last]
Hit the reader in the face with what using this library looks like. Make it copy-pasteable:
## Example
```typescript
import { doThing } from 'library-name';
const result = doThing({ option: 'value' });
console.log(result);
// => Expected output
```
Include package manager commands and prerequisites:
## Installation
```bash
npm install library-name
```
### Prerequisites
- Node.js >= 18.0.0
- TypeScript >= 5.0 (if using TypeScript)
For applications, use this section order:
# app-name
One sentence describing the application.
## Documentation
[Quick links to external docs, if they exist]
## Features
[Bullet points highlighting capabilities]
## Quick Start
### Installation
[Installation commands]
### Prerequisites
[Required dependencies]
## Usage
[How to use the application]
## Advanced Usage
[If applicable]
## Configuration
[If applicable]
## Development
[If ARCHITECTURE.md, DEVELOPMENT.md, or CONTRIBUTING.md exist]
## Acknowledgements
[If applicable - penultimate section]
## License
[Always last]
Use bullet points, be specific:
## Features
- **Fast** — Processes 10,000 files per second
- **Zero config** — Works out of the box
- **Extensible** — Plugin system for custom behavior
For monorepo root READMEs, serve as an index:
# monorepo-name
One sentence describing the monorepo's purpose.
## Packages
| Package | Description |
| ------------------------- | ----------- |
| [package-a](./packages/a) | Does X |
| [package-b](./packages/b) | Does Y |
## Development
[Link to DEVELOPMENT.md, CONTRIBUTING.md if they exist]
## Acknowledgements
[If applicable - penultimate section]
## License
[Always last]
Do not include Example, Installation, Usage, or Configuration sections in monorepo root READMEs—those belong in individual package READMEs.
Add this section if any of these files exist in the project:
ARCHITECTURE.mdDEVELOPMENT.mdCONTRIBUTING.md## Development
See [DEVELOPMENT.md](DEVELOPMENT.md) for setup instructions.
For architecture details, see [ARCHITECTURE.md](ARCHITECTURE.md).
Contributions welcome! Read [CONTRIBUTING.md](CONTRIBUTING.md) first.
Ask the user before adding this section:
Should I include a "Motivation" section explaining why this project exists?
If yes, explain the problem being solved and why existing solutions were insufficient.
Ask the user before adding this section:
Should I include a "Project Scope" section listing what's in and out of scope?
Format if yes:
## Project Scope
### In Scope
- Feature X
- Use case Y
### Out of Scope
- Feature Z (use [other-tool] instead)
- Use case W
Add if external resources are known. Otherwise, ask the user:
Are there external resources (blog posts, videos, related projects) I should link to?
## Resources
- [Blog post about X](https://example.com)
- [Video tutorial](https://youtube.com/...)
- [Related project](https://github.com/...)
Ask the user before adding:
Are there projects or individuals that heavily inspired this work and should be acknowledged?
This section should always be the penultimate section (just before License):
## Acknowledgements
This project was inspired by [other-project](https://github.com/...) and builds on ideas from [person]'s work on [thing].
Check for markdownlint config files in the project root:
.markdownlint.json.markdownlint.yaml.markdownlint-cli2.yaml.markdownlintrcIf present, follow its rules.
Avoid this pattern:
**Configuration Options:**
Markdownlint won't flag it (the colon makes it "okay"), but it's harder to navigate. Use proper subheadings:
#### Configuration Options
Always specify the language. If there's no specific language, use text:
```text
Some plain output here
```
Common languages: bash, typescript, javascript, json, yaml, markdown, text
No markup in headings:
<!-- Bad -->
## `Config` Options
## **Important** Notes
<!-- Good -->
## Config Options
## Important Notes
writing-clearly-and-concisely skill