From am-plugin
Use this skill when editing, generating, or improving a README.md file. Triggers: any mention of 'README', 'readme', documentation for a project, project description, badges, table of contents, or when the user asks to document a codebase. Also triggers when analyzing an existing README for improvements. Covers: structure, badges, TOC, feature sections, tech stack tables, installation guides, contributing guidelines, license sections, and bilingual READMEs.
npx claudepluginhub astyanm/claude-am-plugin --plugin am-pluginThis skill uses the workspace's default tool permissions.
A README is the front door of your project. It should answer three questions in under 30 seconds:
Verifies tests pass on completed feature branch, presents options to merge locally, create GitHub PR, keep as-is or discard; executes choice and cleans up worktree.
Guides root cause investigation for bugs, test failures, unexpected behavior, performance issues, and build failures before proposing fixes.
Writes implementation plans from specs for multi-step tasks, mapping files and breaking into TDD bite-sized steps before coding.
Share bugs, ideas, or general feedback.
A README is the front door of your project. It should answer three questions in under 30 seconds:
Everything else is progressive disclosure.
cat package.json → name, version, description, scripts, dependenciesls src/ → project structuregit remote -v → repo URL for badgescat LICENSE → license typecat .env.example → required environment variables# Project Name
Short one-liner description (matches package.json description).
 ← optional, high impact
## Badges (optional)
## Features
## Demo / Live Site
## Tech Stack
## Getting Started
### Prerequisites
### Installation
### Environment Variables
### Running Locally
## Usage / Examples
## Project Structure
## Scripts Reference
## API Reference (if applicable)
## Roadmap
## Contributing
## License
## Acknowledgments
Not every project needs every section. Use judgment:
# Project Name
One-sentence description. No marketing fluff. State what it does.
package.json description field if availableGenerate badges from real project data. Use shields.io format:
Common badge categories:
Rules:
## Features
- **Feature name** — Short description of what it does and why it matters
- **Another feature** — Concrete benefit, not vague marketing
Rules:
Use a table for readability:
## Tech Stack
| Category | Technologies |
|---------------|---------------------------------------|
| Framework | Astro 5, React 19 |
| Styling | Tailwind CSS 3.4, CSS custom props |
| Content | Markdown/MDX, Zod schema validation |
| Deployment | GitHub Pages, GitHub Actions |
Rules:
package.json## Getting Started
### Prerequisites
- Node.js >= 18
- pnpm (recommended) or npm
### Installation
git clone https://github.com/USER/REPO.git
cd REPO
pnpm install
### Environment Variables
Copy `.env.example` to `.env` and fill in the values:
cp .env.example .env
| Variable | Description | Required |
|-------------------|--------------------------|----------|
| `DATABASE_URL` | PostgreSQL connection | Yes |
| `API_KEY` | Third-party API key | No |
### Running Locally
pnpm dev
Rules:
package.json — use the ACTUAL commands.env.example exists, document every variable## Project Structure
src/
├── components/ # Reusable UI components
├── layouts/ # Page layouts
├── pages/ # Route pages (file-based routing)
├── content/ # MDX content collections
├── styles/ # Global styles and Tailwind config
├── lib/ # Utility functions and helpers
└── assets/ # Static assets (images, fonts)
Rules:
ls / find output — never invent structurenode_modules, .git, dist, build## Scripts
| Command | Description |
|-------------------|--------------------------------|
| `pnpm dev` | Start dev server on :4321 |
| `pnpm build` | Production build to `./dist` |
| `pnpm preview` | Preview production build |
| `pnpm lint` | Run ESLint |
| `pnpm test` | Run test suite |
Rules:
package.json## License
This project is licensed under the MIT License — see [LICENSE](LICENSE) for details.
When asked to edit (not generate from scratch):
Common edit requests and how to handle them:
Two approaches depending on content length:
Approach A — Language switcher (recommended for shorter READMEs):
# Project Name
🇬🇧 [English](#english) | 🇫🇷 [Français](#français)
---
## English
[Full content in English]
---
## Français
[Full content in French]
Approach B — Separate files (for longer READMEs):
README.md ← Default language (usually English)
README.fr.md ← French version
With a link at the top of each:
🇫🇷 [Version française](README.fr.md)
Rules:
Generate TOC from actual headings in the file:
## Table of Contents
- [Features](#features)
- [Tech Stack](#tech-stack)
- [Getting Started](#getting-started)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Project Structure](#project-structure)
- [License](#license)
Rules:
Before finishing any README edit, verify:
bash, json, etc.)$ prefix, no > prefix)package.jsongit remote -v).env.example variables are all documentedpackage.json scripts$ or > before shell commands (breaks copy-paste)