| name | readme-generator |
| description | Generate professionally formatted README.md files following a specific centered table-based structure. Use when creating or reformatting README files for GitHub repositories, particularly for Ghost's projects across 48hour-solutions, Automotive-9, LLMTooling, MCDxAI, Orbital-8, Parallel-7, and GhostTypes organizations. Triggers include "create a readme", "reformat this readme", "update the readme", or any request to document a repository. |
README Generator
This skill generates README.md files following a specific centered, table-based structure with strict formatting rules.
Core Layout Structure
Every README follows this exact top section structure:
<div align="center">
# Project Title
_if icon available_
**One-line summary/tagline describing the project**
  
**Bold statement highlighting the core value proposition**
</div>
Strict Formatting Rules
NEVER USE
- ❌ Emojis (anywhere in the document)
- ❌ Standalone bulleted lists (bullets within table cells are OK)
- ❌ Horizontal rule separators (
---) between sections
ALWAYS USE
- ✓ Centered layout for all elements except standalone code blocks
- ✓ Tables for all feature lists, steps, workflows, and organized content
- ✓ Markdown formatting within table cells
- ✓ shields.io badges with appropriate colors matching the tech stack
Special Rules for Code Blocks
CRITICAL: Markdown code blocks CANNOT be placed inside <div align="center"> tags as it breaks GitHub rendering.
- If a code block is needed outside a table → place it WITHOUT center tags
- All other elements → MUST be centered
- Code blocks within table cells → perfectly fine
Badge Generation
Always Use shields.io
Format: https://img.shields.io/badge/{LABEL}-{MESSAGE}-{COLOR}?style=flat
Color Selection Strategy
Match colors to the technology/library branding:
- Status badges:
purple for preview/beta, brightgreen for stable, yellow for experimental
- Minecraft:
0ea5e9 (light blue)
- Fabric Loader:
f59e0b (amber)
- Java:
orange or 007396
- Python:
3776ab or yellow
- TypeScript:
3178c6
- Node.js:
339933
- Vue:
4fc08d
- React:
61dafb
Version Discovery Process
REQUIRED: Before generating badges, examine the codebase:
- JavaScript/TypeScript projects: Check
package.json for dependencies
- Java projects: Check
build.gradle, build.gradle.kts, pom.xml
- Python projects: Check
pyproject.toml, requirements.txt, setup.py
- Other languages: Look for standard dependency files
If you cannot find version information → ASK before generating the README
Use actual version numbers when found, or "latest" as fallback only if user confirms.
Content Structure
All content sections use clean, centered tables with two columns:
<div align="center">
| Category/Label | Details/Description |
| --- | --- |
| **First Item** | Detailed information with **markdown** and `code` |
| **Second Item** | More details • Sub-bullets OK here • Another point |
</div>
Standard Section Pattern
Follow this structure closely (based on meteor-client-webgui):
- Feature Highlights - Key capabilities in table format
- Quick Start - Installation and setup steps in table format
- Development Workflow - Commands and development info in table format
Table Design Guidelines
- Left column: Short, bold labels or categories (1-3 words)
- Right column: Detailed information with full markdown support
- Within cells: Use
• for sub-points, **bold** for emphasis, `code` for commands
- Multi-line content: Perfectly fine within cells
- Code blocks in cells: Use triple backticks with language identifier
Formatting Lists Within Table Cells
CRITICAL: When adding lists or multi-line content within table cells, use these exact patterns for proper rendering:
Numbered lists with line breaks:
| **Step** | 1. First action<br>2. Second action<br>3. Third action |
Indented bullets under numbered items:
| **Step** | 1. Main instruction<br> • **Sub-item**: Detail<br> • **Another**: More detail<br>2. Next step |
Simple bullet lists (inline):
| **Feature** | Main description • First point • Second point • Third point |
Multi-line bullet lists (each bullet on its own line):
| **Issue** | Problem description | • First solution item<br>• Second solution item<br>• Third solution item<br>• Fourth solution item |
This renders as a clean vertical list within the cell, like:
- • First solution item
- • Second solution item
- • Third solution item
- • Fourth solution item
Important notes:
- Use
<br> for line breaks within cells (NOT actual newlines)
- Use
• for indented bullets (3 non-breaking spaces + bullet character)
- Bold labels within bullets:
• **Label**: description
- For vertical lists, place
<br> BETWEEN bullet items (after item, before next bullet)
- The pattern MUST be exact or GitHub won't render it correctly
Real-world example from troubleshooting table:
| **Discovery Not Finding Printer** | Automatic discovery doesn't detect your printer | • Ensure printer is on the same network/subnet as Home Assistant<br>• Check firewall settings (UDP port 18007 must be open)<br>• Verify LAN mode is enabled on the printer<br>• Try manual configuration with IP address |
This renders as a clean, readable vertical list in the Solutions column.
Complex example with numbered steps and sub-bullets:
| **Installation** | 1. Open **HACS** in Home Assistant<br>2. Click on **Integrations**<br>3. Add repository:<br> • **URL**: `https://github.com/user/repo`<br> • **Category**: `Integration`<br>4. Click **Download** |
Codebase Analysis Process
When NO existing README exists
REQUIRED: Thoroughly analyze the codebase before writing:
- Identify the project type (library, application, tool, addon, etc.)
- Find the tech stack (languages, frameworks, dependencies)
- Discover features by examining:
- Main source files and their public APIs
- Configuration files and what they configure
- Build scripts and what they produce
- Documentation comments in code
- Example/test files showing usage
- Extract version information from dependency files
- Identify setup requirements (install steps, dependencies, system requirements)
- Note any special considerations (permissions, compatibility, known issues)
Never guess or hallucinate features - only document what's actually in the code.
When existing README exists
Default behavior: Reformat to the centered table structure while preserving factual content
Process:
- Extract all factual information (features, versions, installation steps, etc.)
- Strip out emojis completely
- Convert bulleted lists to centered tables
- Reorganize into the standard section structure
- Update badge formatting to shields.io style
- Ensure all elements are properly centered (except standalone code blocks)
- Keep the same level of technical detail
Exception: If user says "rewrite" or indicates content changes needed, then also revise the content itself.
Section Guidelines
Features/Highlights Section
Format as a table with specific feature areas:
<div align="center">
| Capability | Details |
| --- | --- |
| **Feature Name** | Clear description of what it does and why it matters |
| **Another Feature** | Technical details with code examples if needed |
</div>
Quick Start Section
Format as a table with numbered steps or clear categories:
<div align="center">
| Step | Instructions |
| --- | --- |
| **1. Requirements** | List dependencies • version requirements • system requirements |
| **2. Installation** | Download, install, setup commands |
| **3. First Run** | How to verify it works |
</div>
Development Workflow Section
Format as a table organizing by component or task:
<div align="center">
| Component | Commands / Actions |
| --- | --- |
| **Build** | `./gradlew build` – Compiles and packages |
| **Test** | `npm test` – Runs test suite |
| **Dev Server** | `npm run dev` – Hot reload on localhost:3000 |
</div>
Tone and Style
- Professional and technical: Direct, clear, factual
- No fluff: Every sentence should provide value
- Scannable: Users should quickly find what they need
- Complete but concise: Include necessary details without verbosity
Contributing Section
DO NOT INCLUDE a Contributing section unless explicitly requested.
Ghost adds this manually when needed.
Example References
Primary Reference: Home Assistant Integration
See references/homeassistant-example.md for a comprehensive, perfect example demonstrating:
- Multi-column tables with rowspan for categorization
- Section headers as centered H2 (
<h2>) elements
- Complex table cells with rich formatting (line breaks, bullets, bold, code)
- Subsections within centered divs using H3
- Varied table structures (2-column, 3-column, 4-column)
- Code blocks properly placed outside center tags
- Professional technical documentation for a real-world project
Additional Reference
https://github.com/MCDxAI/meteor-client-webgui/blob/main/README.md
Study these examples closely for:
- Exact centering approach
- Table structure and formatting
- Badge selection and colors
- Section organization
- Markdown within tables
- Professional technical tone
Validation Checklist
Before presenting the README, verify:
