# Readme Writer

> Create or update a concise project README.md using the required template baseline. Use when a project needs a new README, when an existing README is stale or incomplete, or when README structure should be normalized for fast engineer onboarding.

- Skill: `twistingmercury/readme-writer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add twistingmercury/readme-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/twistingmercury/readme-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: twistingmercury (https://skillmd.com/u/twistingmercury)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/twistingmercury/readme-writer

---


# README Writer Skill

Create or update the root `README.md` using `templates/README.template.md` as the minimum required structure.

## Inputs

Collect:

- Project name and purpose
- Maturity level (`Emerging`, `Basic`, or `Mature`)
- Existing documentation to reference
- Build/test/versioning commands that should be runnable

## Workflow

1. Read existing root `README.md` if present.
2. Inspect repository context (`git ls-files` if git repo; otherwise walk directory).
3. Draft README using template sections as required minimum.
4. Add extra sections only when they materially reduce onboarding time.
5. Keep README concise. If setup or getting-started content grows large, move details to a dedicated doc and link to it from README.
6. For versioning, if tags are missing, always fall back to `v0.0.1`.
7. Verify that README has no placeholders, no broken section headings, and commands are realistic for the repo.

## Published-document preservation

Before editing generated documentation, inspect Git history and upstream or remote-tracking refs. Preserve published standalone documents by creating the next snake_case version with synchronized `Version`, `Date`, and `Notes` metadata. If publication status is uncertain, treat committed documents as published. The root `README.md` is a canonical living file that requires a fixed path and may be updated in place; apply the versioning rule to dedicated documents split out from it.

## Output Quality Bar

- Use clear, direct prose.
- Prioritize quick project orientation over exhaustive reference material.
- Keep section depth shallow; link out to longer docs instead of expanding inline.