README Standards (v2025.1)
This skill provides README.md templates and standards for projects.
Overview
A well-structured README is the front door to your project. It should:
- Immediately communicate what the project does
- Look professional with proper branding
- Provide clear getting started instructions
- Be scannable with good visual hierarchy
Template Styles
Minimal Style
Best for: Libraries, small utilities, internal tools
# project-name
[](LICENSE)
Brief description of what this project does.
## Installation
npm install package-name
## Usage
import { feature } from 'package-name'; feature();
## License
MIT
Standard Style (Recommended)
Best for: Most projects, applications, services
<div align="center">
<img src="assets/logo.png" alt="Project Logo" width="128">
# Project Name
**A compelling tagline that explains the project's purpose**
[](LICENSE)
[](https://github.com/OWNER/REPO/stargazers)
[](https://github.com/OWNER/REPO/actions)
[]()
</div>
## Features
- **Feature One** - Description of the first key capability
- **Feature Two** - Description of the second key capability
- **Feature Three** - Description of the third key capability
- **Feature Four** - Description of the fourth key capability
## Tech Stack
| Category | Technology |
|----------|------------|
| Runtime | Bun 1.x |
| Framework | Fastify |
| Frontend | React 18, Vite |
| Database | SQLite (Drizzle ORM) |
| Testing | Vitest, Playwright |
## Getting Started
### Prerequisites
- [Bun](https://bun.sh) >= 1.0
- [Node.js](https://nodejs.org) >= 20 (optional)
### Installation
Clone the repository
git clone https://github.com/OWNER/REPO.git cd REPO
Install dependencies
bun install
Start development server
bun run dev
### Development Commands
bun run dev # Start development server bun run build # Build for production bun run test # Run tests bun run lint # Run linter
## Project Structure
project-name/ ├── src/ │ ├── client/ # Frontend React application │ │ ├── components/ # UI components │ │ └── stores/ # State management │ ├── server/ # Backend Fastify server │ │ ├── routes/ # API endpoints │ │ └── services/ # Business logic │ └── shared/ # Shared types and utilities ├── tests/ # Test files ├── docs/ # Documentation └── README.md
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the [MIT License](https://github.com/laurigates/claude-plugins/blob/HEAD/configure-plugin/skills/readme-standards/LICENSE).
Detailed Style
Best for: Open source projects, documentation-heavy projects, developer tools
Includes everything from Standard plus:
- Architecture diagrams (Mermaid)
- API reference section
- Detailed configuration options
- Changelog link
- Security policy
- Code of conduct reference
Badge Reference
Repository Status Badges
<!-- License -->
[](LICENSE)
<!-- Stars -->
[](https://github.com/OWNER/REPO/stargazers)
<!-- Forks -->
[](https://github.com/OWNER/REPO/network/members)
<!-- Issues -->
[](https://github.com/OWNER/REPO/issues)
<!-- Last Commit -->
[](https://github.com/OWNER/REPO/commits)CI/CD Status Badges
<!-- GitHub Actions -->
[](https://github.com/OWNER/REPO/actions)
<!-- With specific workflow -->
[](https://github.com/OWNER/REPO/actions/workflows/build.yml)
<!-- Codecov -->
[](https://codecov.io/gh/OWNER/REPO)Package Registry Badges
<!-- npm -->
[](https://www.npmjs.com/package/PACKAGE)
[](https://www.npmjs.com/package/PACKAGE)
<!-- PyPI -->
[](https://pypi.org/project/PACKAGE/)
[](https://pypi.org/project/PACKAGE/)
<!-- Crates.io -->
[](https://crates.io/crates/PACKAGE)
[](https://docs.rs/PACKAGE)
<!-- Go -->
[](https://pkg.go.dev/github.com/OWNER/REPO)Technology Badges
<!-- Runtime/Language -->
[]()
[]()
[]()
[]()
<!-- Runtime -->
[]()
[]()
[]()
<!-- Frameworks -->
[]()
[]()
[]()
[]()Logo Guidelines
Recommended Specifications
- Format: PNG (with transparency) or SVG
- Size: 128x128px to 512x512px
- Location:
assets/logo.pngorassets/icon.svg
Centering Logo
<div align="center">
<img src="assets/logo.png" alt="Project Name" width="128">
</div>Using Emoji as Placeholder
If no logo exists:
<div align="center">
# 🚀 Project Name
</div>Common project type emojis:
- 🚀 - General/deployment tools
- 🛠️ - Developer tools
- 📊 - Data/analytics
- 🔒 - Security
- 🌐 - Web applications
- 📱 - Mobile apps
- 🤖 - AI/ML projects
- 📦 - Package/library
Section Guidelines
Features Section
Write features as benefits, not just capabilities:
Good:
- **Automatic Scanner Detection** - Discovers eSCL-compatible scanners via mDNS without manual configuration
- **Smart Photo Separation** - Intelligently detects and crops multiple photos from a single scan using edge analysisCompare — implementation-focused (less effective):
- Uses mDNS for scanner discovery
- Has edge detection algorithmTech Stack Section
Use a table for clarity:
| Category | Technology |
|----------|------------|
| Runtime | Bun 1.x |
| Server | Fastify 4 |
| Frontend | React 18, Tailwind CSS |
| Database | SQLite (Drizzle ORM) |Getting Started Section
Always include:
- Prerequisites with version requirements
- Clone instructions
- Install dependencies command
- Run command
- (Optional) Environment setup
Project Structure Section
- Keep it to 2-3 levels deep
- Only show meaningful directories
- Add brief comments for non-obvious folders
project/
├── src/ # Source code
├── tests/ # Test files
├── docs/ # Documentation
└── scripts/ # Build/dev scriptsProject Type Specific Templates
CLI Tool
## Installation
With npm
npm install -g tool-name
With Bun
bun install -g tool-name
Or run directly
npx tool-name
## Usage
tool-name <command> [options]
Commands: init Initialize a new project build Build the project deploy Deploy to production
Options: -h, --help Show help -v, --version Show version
Library/Package
## Installation
npm install package-name
or
bun add package-name
## Usage
import { feature } from 'package-name';
const result = feature({ option: 'value' });
## API
### `feature(options)`
Description of the function.
**Parameters:**
- `options.key` (string) - Description
**Returns:** `ReturnType` - Description
Web Application
## Demo
🌐 [Live Demo](https://demo.example.com)
## Screenshots
<div align="center">
<img src="docs/screenshots/dashboard.png" alt="Dashboard" width="600">
</div>
## Environment Variables
Create a `.env` file:
DATABASE_URL=postgresql://... API_KEY=your-api-key
Compliance Checklist
Minimal Style
- [ ] Title (h1)
- [ ] Description (1-2 sentences)
- [ ] License badge
- [ ] Installation instructions
- [ ] Basic usage example
- [ ] License section
Standard Style (all of minimal plus)
- [ ] Logo or emoji header
- [ ] 3+ badges (license, stars, CI)
- [ ] Features section (4+ items)
- [ ] Tech stack table
- [ ] Prerequisites
- [ ] Development commands
- [ ] Project structure
- [ ] Contributing mention
Detailed Style (all of standard plus)
- [ ] Architecture diagram
- [ ] API reference or link
- [ ] Configuration options
- [ ] Changelog link
- [ ] Security policy mention
- [ ] Code of conduct mention
Cookiecutter Integration
For creating entire new projects from templates, consider using cookiecutter:
# Install cookiecutter
pip install cookiecutter
# or
uv tool install cookiecutter
# Create project from template
cookiecutter https://github.com/your-org/project-templateCookiecutter is ideal for:
- Creating multiple projects with consistent structure
- Organization-wide project templates
- Including not just README but entire project scaffolding
The /configure:readme command is better for:
- Updating existing projects
- Generating README for projects that already have code
- Compliance checking of existing READMEs