Readme Maintainer

README Maintainer

Guide for maintaining and improving README.md files using GitHub's advanced formatting capabilities.

Core Principle

README.md is user documentation (unlike CLAUDE.md which is Claude's memory). Optimize for scannability, visual appeal, and information hierarchy.

GitHub Advanced Formatting

Tables

Use tables for structured comparisons, feature matrices, and option lists.

Syntax:

| Header 1 | Header 2 | Header 3 |
|----------|:--------:|---------:|
| Left     | Center   | Right    |

Alignment: :--- (left), :---: (center), ---: (right)

Formatting in cells: Supports **bold**, *italic*, `code`, and links.

Escape pipes: Use \| for literal pipe characters.

When to use tables:

• Feature comparisons (columns: feature, description, status)
• Command reference (columns: command, description, example)
• Configuration options (columns: option, type, default, description)
• Side-by-side comparisons (with/without, before/after)

When NOT to use tables:

• Simple lists with no comparison dimension
• Content requiring long prose descriptions

Collapsible Sections

Use <details> for optional or lengthy content that shouldn't dominate the page.

Syntax:

<details>
<summary>Click to expand</summary>

Content here (leave blank line after summary tag)

</details>

Open by default: Add open attribute: <details open>

When to collapse:

• Installation instructions for multiple platforms/methods
• Troubleshooting sections
• Advanced configuration
• Long code examples
• Changelog/version history
• FAQ sections

When NOT to collapse:

• Critical getting-started content
• Primary installation method
• Core features (these should be visible)

Badges

Badges communicate project status at a glance. Use shields.io for consistent styling.

Common badges:

Badge placement: Immediately after title, before description.

Don't overdo it: 3-6 relevant badges. Skip badges for metrics that don't matter.

Mermaid Diagrams

GitHub renders Mermaid diagrams in fenced code blocks.

CRITICAL RULES:

1. Keep node labels SHORT (1-2 words max) - Long labels get truncated
2. Do NOT use %%{init:...}%% theme blocks - These cause node sizing issues that truncate text
3. DO use style directives - Individual node styling works fine
4. Use flowchart LR - Left-to-right works best on GitHub

Flowchart with colors:

```mermaid
flowchart LR
    A[Start] --> B{Ready?}
    B -->|Yes| C[Run]
    B -->|No| D[Wait]

    style A fill:#6366f1,color:#fff
    style C fill:#16a34a,color:#fff
    style D fill:#dc2626,color:#fff
```

Sequence diagram:

```mermaid
sequenceDiagram
    participant U as User
    participant A as API
    participant D as DB
    U->>A: Request
    A->>D: Query
    D-->>A: Result
    A-->>U: Response
```

When to use diagrams:

• Architecture overviews
• Data flow / message flow
• State machines
• Decision trees
• Component relationships

When NOT to use diagrams:

• Simple linear processes (use numbered list)
• When prose is clearer
• Decorative purposes (diagram must clarify)

Best practices:

• Max 1-2 words per node label
• Never use %%{init:...}%% theme configuration (causes truncation)
• Use style NodeId fill:#color,color:#fff for colored nodes
• Use edge labels for relationships (-->|label|)
• Common colors: #6366f1 (indigo), #16a34a (green), #dc2626 (red)
• Put detailed explanations in surrounding text or tables
• Test diagram renders on GitHub before committing

GitHub Alerts

Special blockquotes for callouts.

> [!NOTE]
> Useful information that users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information users need to know.

> [!WARNING]
> Urgent info that needs immediate attention.

> [!CAUTION]
> Advises about risks or negative outcomes.

Renders as colored callout boxes on GitHub.

Code Blocks

Always specify language for syntax highlighting.

```typescript
const example: string = "highlighted";
```

Common language identifiers: typescript, javascript, python, bash, json, yaml, markdown, rust, go

README Structure

Recommended Section Order

1. Title + badges
2. Tagline (1-2 sentences)
3. Table of Contents (collapsible for long READMEs)
4. Why / Motivation (optional)
5. Features (table or list)
6. Quick Start / Installation
7. Usage (with examples)
8. Configuration / API
9. Architecture (if complex, use diagram)
10. Contributing
11. License

See templates/structure.md for detailed template.

Title Format

# Project Name

[![CI](badge-url)](link) [![npm](badge-url)](link) [![License](badge-url)](link)

> One-line description of what this project does.

Table of Contents

For READMEs with 5+ sections, add a collapsible ToC:

<details>
<summary>Table of Contents</summary>

- [Installation](#installation)
- [Usage](#usage)
- [API](#api)
- [Contributing](#contributing)

</details>

Anti-Patterns

Don't Over-Format

• Not every list needs to be a table
• Not every section needs to be collapsed
• Not every process needs a diagram
• Not every statement needs a badge

Don't Add Noise

• Skip badges for metrics that don't matter
• Skip diagrams that don't clarify
• Skip collapsibles for short content
• Skip emojis unless they add meaning

Preserve Author Intent

When beautifying an existing README:

• Respect the existing structure if it's reasonable
• Don't force a completely different format
• Enhance, don't replace
• Keep the author's voice

Beautify Algorithm

1. Read current README.md
2. Identify improvement opportunities:
   • Lists that could be tables (comparisons, options)
   • Long sections that could be collapsed
   • Missing badges (if package.json/CI exists)
   • Architecture that could use a diagram
   • Missing Table of Contents
3. Prioritize user instructions if provided
4. Apply changes incrementally with Edit tool
5. Report what was changed

Breakout Heuristics

For large READMEs (> 400 lines) that should be split into modular documentation.

Thresholds:

• Total lines > 400 → Consider breakout
• Single section > 75 lines → Break out to dedicated file
• Target after breakout: 200-350 lines

Algorithm:

1. Read README.md and count lines
2. Parse sections by heading level
3. Classify sections by keywords (Contributing → CONTRIBUTING.md, etc.)
4. Present breakout plan as table
5. Confirm with user before changes
6. Execute and add Documentation links table

Details: Read ${CLAUDE_PLUGIN_ROOT}/skills/readme-maintainer/templates/breakout.md for:

• GitHub special files (CONTRIBUTING.md, SECURITY.md, etc.)
• Content type detection keywords
• docs/ folder structure
• Post-breakout README template

References

Read these templates for detailed syntax and examples: