tomevault-io 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
```bash
npm install package-name
Usage
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
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.
### 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
<!-- 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 analysis
Compare — implementation-focused (less effective):
- Uses mDNS for scanner discovery
- Has edge detection algorithm
Tech 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 scripts
Project Type Specific Templates
CLI Tool
## Installation
```bash
# 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
```markdown
## Installation
```bash
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
```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 READMEs
Converted and distributed by TomeVault — claim your Tome and manage your conversions.