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
\`\`\`
1---2name: md-style3description: Writing style when writing readme documentation. Always use when creating or updating README.md files.4---56STARTER_CHARACTER = 📝78# README Style Guide910Write concise, direct README files for experienced engineers.1112# Skills1314- use the /md-writer skill for markdown conventions and syntax rules15- use the /md-style skill for writing and language style1617## Principles1819- **No fluff** - Skip tables of contents, verbose explanations, development history20- **No roadmaps** - Document current state only, not plans or decisions. Readme is an engineering specification. Not a project plan or changelog.21- **No repetition** - Each fact appears once22- **No marketing language** - Avoid "next generation", "production ready", "powerful", "comprehensive" and similar hyperbole23- **Direct voice** - State facts, not opinions24- **No contrasting embellishments** - Avoid like "not just a thing, it's a better thing", "not only a thing, it's something", "more than a"2526## Structure Template2728```markdown29# Component Name3031One-line description of what it does.3233## Usage3435\`\`\`bash36./install.sh37./uninstall.sh38\`\`\`3940## Architecture4142| Component | Description |43|-----------|-------------|44| Item 1 | What it is |45| Item 2 | What it is |4647## Configuration4849Key variables and their purpose. Use tables for structured data.5051## Testing5253\`\`\`bash54# Essential verification commands only55make test56\`\`\`5758## File Structure5960\`\`\`text61component/62├── install.sh63├── uninstall.sh64└── manifests/65\`\`\`66```6768## Guidelines6970### Include71- Purpose (one line)72- Install/uninstall commands73- Key configuration (tables preferred)74- Verification commands75- File structure (if non-obvious)7677### Exclude78- Tables of contents79- Prerequisites lists (assume competent audience)80- Verbose troubleshooting guides81- Development decisions/history82- Future plans/roadmaps83- Lengthy explanations of concepts84- Multiple examples of similar things8586### Formatting87- Tables for structured data (components, variables, test coverage)88- Code blocks for commands and examples89- Bold for emphasis sparingly90- No emojis unless explicitly requested91- No emdashes9293## Example Transformation9495**Before (verbose):**96```markdown97## Purpose9899This module provides comprehensive networking infrastructure including100Virtual Networks, Subnets, Network Security Groups, and NAT Gateways.101The architecture follows Azure best practices for hub-spoke topology...102103### Why We Made These Decisions104105After evaluating several approaches, we decided to use service endpoints106because they provide a simpler implementation path without requiring...107```108109**After (concise):**110```markdown111# Networking Module112113Creates VNet, subnets, NSG, NAT Gateway, and service endpoints.114115## Architecture116117\`\`\`text118VNet (10.x.0.0/22)119├── Main Subnet (10.x.0.0/24) - AKS nodes120└── AGW Subnet (10.x.1.0/24) - Application Gateway121\`\`\`122```
jimweller