| name | crate-readme-writer |
| description | Write or substantially revise a Rust crate's README.md as a concise, user-facing design document. Use whenever creating a crate README, documenting a planned crate, or defining a crate's purpose, role, or interface before implementation. |
Crate README writer
Invoke docs-writer and apply its rules throughout.
For a new crate, write the README before implementing behavior.
Use it as a lightweight specification: changing prose and examples is cheaper than changing code, and a written proposal gives collaborators a concrete design to review.
For an existing crate, inspect its manifest and implementation first so the README describes current behavior rather than an imagined interface.
- Identify the intended reader, the problem the crate solves, and why it belongs in the repository.
- Lead with the crate name and a one- or two-sentence description of its purpose.
- Describe the smallest useful contract: principal capability, expected integration point, and important platform or architectural constraints.
- Add a minimal usage example only when it clarifies the intended API better than prose.
- Revise the proposed interface until it is coherent before committing to implementation details.
- Treat a long or complicated README as design feedback: narrow or split the crate instead of writing an exhaustive specification.
- Link to existing project or protocol documentation rather than duplicating it.
- After implementation, verify every claim and example against the code while preserving the README's concise introductory role.
Write README.md directly.
Keep it short enough to expose unclear scope and unnecessary complexity.
This workflow follows Readme Driven Development.
