md-style
README style guide for concise, direct documentation. Use when writing or editing README files.
How do I install this agent skill?
npx skills add https://github.com/jimweller/clanker-skills --skill md-styleIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides documentation style guidelines and contains no executable code or external references. No security risks were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
README Style Guide
Write concise, direct README files for experienced engineers.
Voice
Prose style is not defined here. The clanker-prose plugin's prose-contract owns it, injected via a SessionStart hook pointer to its two sections:
Ghostwriting for Other Humans- a README is read by another human, so it takes the ghostwriting contract: minimum facts, one fact per sentence, the deletion test on every wordBanned Patterns in All Writing- the catalog of forbidden words and constructions, including hype vocabulary, opposing phrases, phantom-foil contrast, emojis, and emdashes
This skill covers what belongs in a README and in what order.
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.
Structure
Sections in order: Overview, Prerequisites, Usage, Architecture, Configuration, Testing, File Structure. One-line purpose statement at top under H1.
Exclude
- Tables of contents
- 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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/jimweller/clanker-skills/md-style">View md-style on skillZs</a>