Readme standards

Skill CowDogMoo/squad-agents/skills/readme-standards

Standards for writing and evaluating project READMEs — essential sections, progressive disclosure, writing guidelines, project-type variations, and a quality checklist. Use when drafting a README, reviewing an existing one, or deciding what belongs in it. Also loaded by the readme agent as its knowledge base.From its SKILL.md

Install

npx -y skills add CowDogMoo/squad-agents --skill readme-standards

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

16.2 KB, as published. Nobody here has run it

README Standards

A comprehensive guide to writing effective README documentation for software projects. This document serves as the knowledge base for the readme pattern.

Core Principles
Essential Sections
Writing Guidelines
Section Templates
Project Type Variations
Quality Checklist

Core Principles

The Three Questions

A great README answers three fundamental questions in the first few paragraphs:

Question	Answer In
What is this?	Title and first paragraph
Why should I care?	Overview/description
How do I use it?	Quick Start section

Progressive Disclosure

Structure information from general to specific:

Time	User Should
10 seconds	Understand what it is
30 seconds	Know if it's relevant
5 minutes	Get started using it
When needed	Find detailed documentation

Key Principles

Principle	Description
Clarity	Use simple, direct language
Completeness	Include all essential sections
Accuracy	Keep information current
Scannability	Use headings, lists, and code blocks

Essential Sections

Required Sections (In Order)

Project Title - Clear, descriptive name
One-line Description - What it does and who it's for
Overview - 2-3 sentences expanding on the description
Installation - Prerequisites and step-by-step instructions
Quick Start - Working example users can run immediately
Usage - Detailed usage examples
License - License information

Recommended Sections

Section	When to Include
Badges	Public/open source projects
Table of Contents	READMEs longer than 200 lines
Features	Projects with multiple capabilities
Configuration	Projects with config options
API Reference	Libraries with programmatic APIs
Examples	Complex projects
Contributing	Open source projects
Testing	Projects with test suites
Acknowledgments	Projects with contributors/dependencies

Writing Guidelines

Language and Style

DO:

Use simple, direct language in active voice
Write short sentences and paragraphs
Define technical terms on first use
Provide context for decisions

DON'T:

Use vague language ("the usual setup")
Include placeholder text ("TODO", "Coming soon")
Create walls of text
Assume reader knowledge without explanation

Code Examples

Good code examples:

# Install the package
npm install my-package

# Run the example
npm run example

Bad code examples:

# TODO: Add installation command
install-command-here

Formatting

Element	Use For
`# Title`	Main title (use once)
`## Section`	Major sections
`### Subsection`	Subsections
`bold`	Emphasis and key terms
`code`	Variables, commands, file names
`> quote`	Important notes and warnings
Tables	Structured data

Visual Hierarchy

Place key metrics and KPIs prominently
Group related information together
Use consistent panel sizes for related content
Create visual separation between sections
Use rows/sections to organize

Section Templates

Installation Section

## Installation

### Prerequisites

- Node.js 18 or higher
- npm 9 or higher
- Git 2.30+

### Quick Install

\`\`\`bash
npm install my-package
\`\`\`

### From Source

\`\`\`bash
git clone https://github.com/user/project.git
cd project
npm install
npm run build
\`\`\`

### Verification

\`\`\`bash
my-package --version
# Expected output: my-package v1.0.0
\`\`\`

Quick Start Section

## Quick Start

Create your first project in under 60 seconds:

\`\`\`bash
# Initialize a new project
my-package init my-project
cd my-project

# Run the development server
my-package serve
\`\`\`

Open http://localhost:3000 to see your project.
For detailed usage, see the [Usage](#usage) section.

Configuration Section

## Configuration

### Environment Variables

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `API_KEY` | API authentication key | Yes | - |
| `DEBUG` | Enable debug logging | No | `false` |
| `PORT` | Server port | No | `3000` |

### Configuration File

Create a `config.yaml` file:

\`\`\`yaml
server:
  port: 3000
  host: localhost

logging:
  level: info
  format: json
\`\`\`

Contributing Section

## Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes and add tests
4. Run the test suite: `npm test`
5. Commit your changes: `git commit -m 'Add amazing feature'`
6. Push to the branch: `git push origin feature/amazing-feature`
7. Open a Pull Request

### Development Setup

\`\`\`bash
git clone https://github.com/user/project.git
cd project
npm install
npm run dev
\`\`\`

Project Type Variations

CLI Tool

Emphasize:

Command-line usage examples
Available commands and options
Input/output formats
Shell completion setup

Example sections:

## Commands

| Command | Description |
|---------|-------------|
| `init` | Initialize a new project |
| `build` | Build the project |
| `serve` | Start development server |

## Options

| Option | Description |
|--------|-------------|
| `-v, --verbose` | Enable verbose output |
| `-c, --config` | Specify config file |

Library/Package

Emphasize:

API documentation
Code examples for common use cases
Type definitions
Integration examples

Example sections:

## API Reference

### `myFunction(options)`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `options.name` | `string` | Yes | Name of the resource |
| `options.timeout` | `number` | No | Timeout in ms (default: 5000) |

**Returns:** `Promise<Result>`

Web Application

Emphasize:

Live demo link
Screenshots/GIFs
Deployment instructions
Browser support

Example sections:

## Demo

Try the live demo at https://example.com/demo

## Screenshots

![Dashboard](./docs/screenshots/dashboard.png)
*Dashboard view showing key metrics*

Framework/SDK

Emphasize:

Architecture overview
Getting started guide
Plugin/extension system
Migration guides

Monorepo

Emphasize:

Package structure
Workspace commands
Cross-package dependencies
Individual package READMEs

Quality Checklist

Before Publishing

For Open Source

Contributing guidelines
Code of conduct (or link to one)
Issue templates mentioned
Badges for build status, version, license
Acknowledgments for contributors

For Enterprise

Security considerations
Support contact information
SLA information (if applicable)
Compliance/certification info

Badges and Visual Elements

Shields.io Badges

Badges provide at-a-glance project status. Place after title, limit to 5-8.

Recommended badges:

![Build Status](https://img.shields.io/github/actions/workflow/status/username/repo/ci.yml?branch=main)
![Coverage](https://img.shields.io/codecov/c/github/username/repo)
![Version](https://img.shields.io/github/v/release/username/repo)
![License](https://img.shields.io/github/license/username/repo)
![Go Version](https://img.shields.io/github/go-mod/go-version/username/repo)

Badge categories:

Category	Purpose
Build status	CI/CD pipeline status
Coverage	Code coverage percentage
Version	Latest release
License	Project license type
Downloads	Package download count
Social	Stars, forks, contributors

Screenshots and GIFs

Visual elements improve comprehension dramatically.

When to use:

CLI tools → Show terminal output
Web apps → Include screenshots
Libraries → Show code examples with results
Performance tools → Display graphs and metrics

Best practices:

Keep images under 500KB
GIFs max 30 seconds
Provide alt text for accessibility
Store in docs/images/ directory
Use relative paths

Tools:

Tool	Purpose
Terminalizer	Record terminal sessions
asciinema	Terminal recorder
Carbon	Code screenshots
Mermaid	Diagrams in markdown
Excalidraw	Architecture diagrams

Advanced Sections

Architecture Section

For complex projects:

## Architecture

### High-Level Overview

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Client    │────▶│   Gateway   │────▶│   Service   │
└─────────────┘     └─────────────┘     └─────────────┘
                                               │
                                               ▼
                                        ┌─────────────┐
                                        │  Database   │
                                        └─────────────┘

### Components

- **Gateway** - Routes requests, handles authentication
- **Service** - Business logic and data processing
- **Database** - PostgreSQL for persistent storage

See [docs/architecture.md](docs/architecture.md) for details.

Troubleshooting Section

## Troubleshooting

### Connection timeout error

**Symptoms:** Requests fail with timeout after 30 seconds

**Solution:**
1. Check network: `ping api.example.com`
2. Verify firewall allows outbound HTTPS
3. Increase timeout: `export TIMEOUT=60`

### Getting Help

- Check [existing issues](https://github.com/user/repo/issues)
- Ask in [Discussions](https://github.com/user/repo/discussions)
- Join our [Discord](https://discord.gg/example)

Performance Section

## Performance

### Benchmarks

Tested on MacBook Pro M1, 16GB RAM:

| Operation | Time | Memory | Records/sec |
|-----------|------|--------|-------------|
| Parse | 1.2s | 120MB | 833,333 |
| Transform | 0.8s | 80MB | 1,250,000 |

### Optimization Tips

- Use streaming for files over 100MB
- Enable caching with `--cache` flag
- Process in parallel with `--workers=4`

Security Section

## Security

### Reporting Vulnerabilities

Report security issues to [email protected]. Do not open public issues.

### Security Features

- All communication uses TLS 1.3
- Passwords hashed with bcrypt (cost factor 12)
- API keys encrypted at rest using AES-256

### Best Practices

1. Never commit API keys or credentials
2. Use environment variables for secrets
3. Regularly rotate API keys

Deployment Section

## Deployment

### Docker

\`\`\`bash
docker pull username/project:latest
docker run -p 3000:3000 -e API_KEY=$API_KEY username/project:latest
\`\`\`

### Kubernetes

\`\`\`bash
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml
\`\`\`

### Cloud Platforms

- **AWS:** [Deploy to ECS](docs/deploy-aws.md)
- **GCP:** [Deploy to Cloud Run](docs/deploy-gcp.md)
- **Azure:** [Deploy to Container Instances](docs/deploy-azure.md)

Tools and Resources

README Templates

Resource	Description
Best-README-Template	Comprehensive template
Standard Readme	Standardized specification
Readme.so	Visual README editor
Make a README	Simple guide and template

Linters and Validators

Tool	Purpose
markdownlint	Markdown linting
markdown-link-check	Check for broken links
alex	Check for insensitive writing
write-good	Writing style checker

GitHub Action for README Validation

name: README Check
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check links
        uses: gaurav-nelson/github-action-markdown-link-check@v1
      - name: Lint markdown
        uses: DavidAnson/markdownlint-cli2-action@v14

Real-World Examples

Outstanding READMEs

Study these for inspiration:

Project	Notable Feature
esbuild	Performance graphs and benchmarks
Astro	Perfect balance of features and getting started
Supabase	Great visual hierarchy
FastAPI	Excellent documentation
Rich	Visual demonstrations

What Makes Them Great

Answer "what, why, how" immediately
Include working examples
Clear visual hierarchy
Show rather than tell
Maintained and up-to-date

Maintenance

Keep It Current

A README is never "done." Maintain it as you would code.

With each release:

Quarterly:

Review and update prerequisites
Refresh benchmark data
Check for broken links
Update contributor list

Version Your Documentation

## Documentation Versions

- [Latest (main)](README.md)
- [v2.0](https://github.com/user/project/blob/v2.0/README.md)
- [v1.0](https://github.com/user/project/blob/v1.0/README.md)

Get Feedback

Monitor issues for documentation requests
Watch for repeated questions (gaps in docs)
Survey users periodically

Common Mistakes

Too Vague

Bad:

Install the tool using the standard method.
Configure it as needed for your environment.

Good:

Install with npm:
\`\`\`bash
npm install -g mytool
\`\`\`

Configure by creating `~/.mytool.yaml`:
\`\`\`yaml
api_key: your-api-key
region: us-west-2
\`\`\`

Missing Prerequisites

Bad:

## Installation
Run `make install` to install.

Good:

## Installation

### Prerequisites
- Go 1.21 or higher
- Make 4.0+
- PostgreSQL 14+ (for database features)

### Install
\`\`\`bash
make install
\`\`\`

No Working Examples

Bad:

## Usage
Use the API to do things.

Good:

## Usage

\`\`\`python
from mylib import Client

client = Client(api_key="your-key")
result = client.process("Hello, World!")
print(result)
# Output: "HELLO, WORLD!"
\`\`\`

References

Last updated: 2026-01-10

One thing to look at

SKILL.md

README Standards

Table of Contents

Core Principles

The Three Questions

Progressive Disclosure

Key Principles

Essential Sections

Required Sections (In Order)

Recommended Sections

Writing Guidelines

Language and Style

Code Examples

Formatting

Visual Hierarchy

Section Templates

Installation Section

Quick Start Section

Configuration Section

Contributing Section

Project Type Variations

CLI Tool

Library/Package

Web Application

Framework/SDK

Monorepo

Quality Checklist

Before Publishing

For Open Source

For Enterprise

Badges and Visual Elements

Shields.io Badges

Screenshots and GIFs

Advanced Sections

Architecture Section

Troubleshooting Section

Performance Section

Security Section

Deployment Section

Tools and Resources

README Templates

Linters and Validators

GitHub Action for README Validation

Real-World Examples

Outstanding READMEs

What Makes Them Great

Maintenance

Keep It Current

Version Your Documentation

Get Feedback

Common Mistakes

Too Vague

Missing Prerequisites

No Working Examples

References

Keep looking