readme-standards
|
Works with
Claude CodeCursorCodex CLIGitHub CopilotGemini CLI
---
name: readme-standards
description: |
license: MIT
---
# 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
```markdown
# project-name
[](LICENSE)
Brief description of what this project does.
## Installation
```bash
npm install package-name
```
## Usage
```javascript
import { feature } from 'package-name';
feature();
```
## License
MIT
```
### Standard Style (Recommended)
Best for: Most projects, applications, services
```markdown
<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
```bash
# 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
```bash
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](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
```markdown
<!-- 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
```markdown
<!-- 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
```markdown
<!-- 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
```markdown
<!-- Runtime/Language -->
[]()
[]()
[]()
[]()
<!-- Runtime -->
[]()
[]()
[]()
<!-- Frameworks -->
[]()
[]()
[]()
[]()
```
## Logo Guidelines
### Recommended Specifications
- **Format**: PNG (with transparency) or SVG
- **Size**: 128x128px to 512x512px
- **Location**: `assets/logo.png` or `assets/icon.svg`
### Centering Logo
```markdown
<div align="center">
<img src="assets/logo.png" alt="Project Name" width="128">
</div>
```
### Using Emoji as Placeholder
If no logo exists:
```markdown
<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:**
```markdown
- **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 analysis
```
**Compare — implementation-focused (less effective):**
```markdown
- Uses mDNS for scanner discovery
- Has edge detection algorithm
```
### Tech Stack Section
Use a table for clarity:
```markdown
| Category | Technology |
|----------|------------|
| Runtime | Bun 1.x |
| Server | Fastify 4 |
| Frontend | React 18, Tailwind CSS |
| Database | SQLite (Drizzle ORM) |
```
### Getting Started Section
Always include:
1. Prerequisites with version requirements
2. Clone instructions
3. Install dependencies command
4. Run command
5. (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 scripts
```
## Project Type Specific Templates
### CLI Tool
```markdown
## Installation
```bash
# With npm
npm install -g tool-name
# With Bun
bun install -g tool-name
# Or run directly
npx tool-name
```
## Usage
```bash
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
```markdown
## Installation
```bash
npm install package-name
# or
bun add package-name
```
## Usage
```typescript
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
```markdown
## 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:
```env
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](https://cookiecutter.readthedocs.io/):
```bash
# Install cookiecutter
pip install cookiecutter
# or
uv tool install cookiecutter
# Create project from template
cookiecutter https://github.com/your-org/project-template
```
Cookiecutter 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 READMEsMore Writing & Documentation skills
paper-context-resolver
lllllllama/rigorpilot-skills
Rigor Paper Context helper for README-first deep learning repo reproduction. Use only when the README and repository files leave a narrow reproduction-critical gap and the task is to resolve a specific paper detail such as dataset split, preprocessing, evaluation protocol, checkpoint mapping, or runtime assumption from primary paper sources while recording conflicts. Do not use for general paper summary, repo scanning, environment setup, command execution, title-only paper lookup, or replacing README guidance by default.
450.8k
repo-intake-and-plan
lllllllama/rigorpilot-skills
Rigor Intake helper for README-first deep learning repo reproduction. Use when the task is specifically to scan a repository, read the README and common project files, extract documented commands, classify inference, evaluation, and training candidates, and return the smallest trustworthy reproduction plan to the main orchestrator. Do not use for environment setup, asset download, command execution, final reporting, paper lookup, or end-to-end orchestration.
450.0k
minimal-run-and-audit
lllllllama/rigorpilot-skills
Rigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation command and write standardized `repro_outputs/` files, including patch notes when repository files changed. Do not use for training execution, initial repo intake, generic environment setup, paper lookup, target selection, hidden scientific-meaning changes, or end-to-end orchestration by itself.
449.9k
