jimweller/md-style

STARTER_CHARACTER = 📝

README Style Guide

Write concise, direct README files for experienced engineers.

Skills

• use the /md-writer skill for markdown conventions and syntax rules
• use the /md-style skill for writing and language style

Principles

• No fluff - Skip tables of contents, verbose explanations, development history
• No roadmaps - Document current state only, not plans or decisions. Readme is an engineering specification. Not a project plan or changelog.
• No repetition - Each fact appears once
• No marketing language - Avoid "next generation", "production ready", "powerful", "comprehensive" and similar hyperbole
• Direct voice - State facts, not opinions
• No contrasting embellishments - Avoid like "not just a thing, it's a better thing", "not only a thing, it's something", "more than a"

Structure Template

# Component Name

One-line description of what it does.

## Usage

\`\`\`bash
./install.sh
./uninstall.sh
\`\`\`

## Architecture

| Component | Description |
|-----------|-------------|
| Item 1 | What it is |
| Item 2 | What it is |

## Configuration

Key variables and their purpose. Use tables for structured data.

## Testing

\`\`\`bash
# Essential verification commands only
make test
\`\`\`

## File Structure

\`\`\`text
component/
├── install.sh
├── uninstall.sh
└── manifests/
\`\`\`

Guidelines

Include

• Purpose (one line)
• Install/uninstall commands
• Key configuration (tables preferred)
• Verification commands
• File structure (if non-obvious)

Exclude

• Tables of contents
• Prerequisites lists (assume competent audience)
• Verbose troubleshooting guides
• Development decisions/history
• Future plans/roadmaps
• Lengthy explanations of concepts
• Multiple examples of similar things

Formatting

• Tables for structured data (components, variables, test coverage)
• Code blocks for commands and examples
• Bold for emphasis sparingly
• No emojis unless explicitly requested
• No emdashes

Example Transformation

Before (verbose):

## Purpose

This module provides comprehensive networking infrastructure including
Virtual Networks, Subnets, Network Security Groups, and NAT Gateways.
The architecture follows Azure best practices for hub-spoke topology...

### Why We Made These Decisions

After evaluating several approaches, we decided to use service endpoints
because they provide a simpler implementation path without requiring...

After (concise):

# Networking Module

Creates VNet, subnets, NSG, NAT Gateway, and service endpoints.

## Architecture

\`\`\`text
VNet (10.x.0.0/22)
├── Main Subnet (10.x.0.0/24) - AKS nodes
└── AGW Subnet (10.x.1.0/24) - Application Gateway
\`\`\`