Readme Authoring

Deep README workflow—audience, value proposition, quickstart, configuration, troubleshooting, contributing, and badges/links hygiene. Use when bootstrapping repos or improving onboarding for open source or internal libraries.

mike47512@mike47512

Install

openclaw skills install @mike47512/readme-authoring

README Authoring (Deep Workflow)

A README is the front door of a repository. Optimize for time-to-first-success: install, run, verify—then add depth for contributors and operators.

When to Offer This Workflow

Trigger conditions:

New repo; users cannot get running from docs alone
Open-source release needing clear license and support expectations
Internal library consumed by many teams

Initial offer:

Use six stages: (1) audience & promise, (2) above-the-fold, (3) quickstart, (4) configuration & operations, (5) contributing & governance, (6) maintenance). Confirm package ecosystem and license.

Stage 1: Audience & Promise

Goal: First paragraph states what the project does, for whom, and non-goals if confusing.

Exit condition: Reader knows in 30 seconds if this repo matches their need.

Stage 2: Above the Fold

Goal: Title, optional badges (CI, version, license), one screenshot or demo GIF if UI helps.

Practices

Link out to a full docs site when README would exceed ~300 lines

Stage 3: Quickstart

Goal: Copy-paste commands that work on a clean machine; pin versions or point to release tags.

Include

Prerequisites (runtime, tools)
Install and the first command with expected output shape

Stage 4: Configuration & Operations

Goal: Environment variables table with defaults; ports; production notes (TLS, scaling, observability).

Security

Never document real secrets; reference secret stores and rotation

Stage 5: Contributing & Governance

Goal: Link CONTRIBUTING.md, code of conduct, issue/PR templates; security disclosure policy for OSS.

Stage 6: Maintenance

Goal: Changelog link or release notes; owning team; deprecation notices when relevant.

Final Review Checklist

Opening clarifies purpose and audience
Quickstart verified on a fresh machine or CI
Configuration and security expectations documented
Contributing and license paths clear
Maintenance signals (changelog, ownership) present

Tips for Effective Guidance

Run quickstart in CI (Docker or script) for critical OSS projects.
Keep README skimmable; move deep dives to docs/.
For libraries: link API reference and migration guides prominently.

Handling Deviations

Monorepo: root README as an index to packages with one-liner descriptions each.