readme-craft

name

readme-craft

description

Opinionated README authoring guide. Picks a section template by project type (CLI, library, web app, hackathon submission, OSS publication, GitHub profile), curates a small set of upstream tools from the awesome-readme-tools catalog, and enforces a mobile-readable structure. Use this skill whenever the user asks to "write a README", "improve my README", "make the README better", "review my README", or starts a new project that needs a public-facing landing artifact. Complements landing-page-fast (landings), brand-creation (identity), oss-readiness (audit), and content-writer (long-form).

README Craft

The README is the only artifact most readers will ever see. It is the landing page, the install guide, the trust signal, and the marketing deck — compressed into a single Markdown file that has to read well on a phone.

This skill gives Claude an opinion: which sections to include for a given project type, which upstream tools are worth embedding, and which anti-patterns to refuse.

When to use

• The user says "write a README", "improve the README", "review my README", "make this look professional", "what should the README contain", or any variant.
• A new project is being scaffolded and a README.md does not yet exist or is the stub generated by npm init / cargo new / create-next-app.
• A repo is being prepared for OSS publication (often paired with oss-readiness) and the existing README is not adequate for outside readers.
• A hackathon submission needs a README that doubles as the judging deliverable.
• A GitHub profile README is being created or refreshed.

When NOT to use

• The user asks for a landing page on a domain. Use landing-page-fast instead; the README is the in-repo doc, the landing is the marketing site, and they have different content shapes.
• The user asks for long-form blog content or a launch announcement. Use content-writer instead.
• The user asks for documentation beyond the README (API reference, architecture doc, runbook). Those go under docs/, not in the README itself.

Project type → section template

Pick the template that matches what the project is. If two seem to apply, pick the more specific one.

Project README (default — library, CLI, service, web app)

Order matters. Readers scan top-to-bottom on a phone and bail after ~10 seconds if they cannot answer "what is this".

1. Title + one-line tagline. No emoji unless the brand voice requires it. Tagline is a single sentence under 90 characters, answers "what is this" — not "what does it do".
2. Hero artifact (optional but recommended). One of:
   • A screenshot or short asciinema cast for a CLI.
   • A 30-second demo gif for a web/mobile app.
   • A code snippet showing the smallest useful invocation for a library. Avoid hero banners with stock photography. They look unserious.
3. Badges (curated, max ~5). Place inline under the title. See "Badges" below for which ones are signal vs decoration.
4. What is this (~50–150 words). Plain language. What problem it solves and who it is for. Skip technical jargon until later sections.
5. Why (optional). A short "compared to X / Y / Z" if the project sits in a crowded category and the differentiation is non-obvious.
6. Install. Copy-pasteable, single language. If multi-platform, start with the most common case and link to a longer doc for the rest.
7. Quickstart. A working example the reader can run in under 60 seconds. If the project requires API keys or config, show the smallest viable .env first.
8. Usage. Real examples covering 3–5 common cases. Each example one code block, one prose sentence. Resist the urge to dump every flag here — link to docs/ for completeness.
9. Configuration. Tabular if there are >5 options. Otherwise prose.
10. Contributing. One-line pointer to CONTRIBUTING.md if it exists; do not duplicate. If the project does not yet have one, a short "PRs welcome — open an issue first to discuss large changes."
11. License. SPDX identifier + link to LICENSE. One line.

Profile README (GitHub username/username repo)

Different rules. Profile READMEs are personal, short, and discoverable via the GitHub front page. Aim for ~300 words rendered.

1. Greeting + name (one line).
2. What you do (one or two sentences). Role / domain / location is the standard form.
3. Currently working on / interested in. 2–3 bullets, refreshed quarterly.
4. Stats widget (optional — see "Statistical widgets" below). Pick ONE, not three. Stacking widgets makes the profile look busy.
5. Reach me (one or two channels — email, LinkedIn, blog).
6. Skip: badges of every tech you've touched, anime gifs, "I am currently learning React" filler. They read as filler.

Hackathon submission

The README IS the judging deliverable. Judges spend ~3 minutes per project. Optimize for that.

1. Project name + tagline (one line).
2. Demo video link (the most important section — place it FIRST if a video exists; second only to the tagline).
3. Devpost / submission link.
4. What it does + why. Two paragraphs maximum.
5. Tech stack (one paragraph or a small table). Mention any sponsor tech used (often required for prize eligibility).
6. Built at + team + dates.
7. Try it yourself. A working URL + credentials for a demo account, OR a git clone && pnpm install && pnpm dev snippet.
8. Skip: architecture diagrams (link to a separate doc if needed), project roadmap, long retrospective. Save those for the post-event blog post.

OSS publication

This is the README for a project transitioning from "internal / personal" to "public". oss-readiness audits everything around it; this skill owns the README itself.

1. All standard project sections.
2. Status banner near the top: development stage (alpha / beta / stable), supported platforms, support level. Be honest. "Personal project, breaking changes likely" is more useful than "production ready" if it is not.
3. Security policy pointer if SECURITY.md exists.
4. Code of conduct pointer if CODE_OF_CONDUCT.md exists.
5. Adopters / users (optional). Only if real and named with permission.
6. Sponsorship / funding (optional). Only if active.

Badges — what is signal vs what is decoration

Badges below the title work like nutrition labels: dense, scannable, trustworthy. Stack them carefully.

Badge	Signal?	Notes
CI status	Yes	Tells the reader the project builds.
Latest version	Yes	npm / PyPI / crates.io / GitHub release.
License	Yes	SPDX shield, single character of cognitive load.
Test coverage	Maybe	Only if you actually have meaningful tests.
Lines of code	No	Optimizing for line count is a known anti-pattern.
Tech-used (e.g. "made with React")	No	Already implied by the code. Visual noise.
Visitor counter / star count	No	Easy to inflate, signals nothing about quality.
"Awesome" badge	If applicable	Only if actually listed in an Awesome list.
Discord / community	Yes	If active. Dead Discord links hurt trust.

Rule of thumb: every badge should answer a question a reader would otherwise ask. If you cannot articulate the question, drop the badge.

Upstream catalog: dhyeythumar/awesome-readme-tools

This skill builds on the curated list at dhyeythumar/awesome-readme-tools (CC0-1.0 / public domain, ~250 stars, actively maintained as of 2026-05). The upstream owns enumeration; this skill owns the opinionated layer.

For concrete tool recommendations, see recommended-tools.md — Walter-OS curates 8 tools (out of ~55 upstream) with per-tool "use when / avoid when / supply-chain notes". Re-audited quarterly. When the agent needs to pick a specific tool, it consults recommended-tools.md first and falls back to the upstream catalog only if nothing in the curated list fits.

The upstream organises tools into 5 categories. Use the gloss below to pick a category, then walk the upstream list to choose a specific tool.

Statistical widgets

Dynamic SVG cards showing GitHub stats, contribution graphs, Wakatime hours, Spotify activity, language distribution, follower history, etc. Use when:

• Building a profile README and you want one (only one) widget.
• The widget answers a question a recruiter / collaborator would actually ask (e.g. "what languages does this person work in?").

Avoid when:

• The widget is purely decorative (animated gradient text, contribution snake animations) — they age badly and signal "trying too hard".
• You have not verified the upstream is still maintained — many widget hosts have gone dark, leaving broken images on thousands of profile READMEs.

README generators

CLIs and web apps that scaffold a README from a wizard or template.

Default position: do not use generators for the README content itself. Generators produce average-quality output by design, and editing average output is consistently slower than writing your own draft against the section template above. See the "Operator workflow" section below — step 2 is "draft from scratch".

The one narrow exception: generators are acceptable for outline-only scaffolding when you genuinely cannot picture the structure (e.g. your first profile README, or a project type you have never written before). Use the generator to produce the section skeleton, then throw away the generated prose and write each section from scratch against the templates above. Never ship generator prose.

Avoid entirely when:

• The generator embeds telemetry, attribution links, or backlinks you cannot remove.
• You already have any draft — even a bad one. Editing your draft beats reading and rewriting the generator's.

GitHub Actions for READMEs

Workflows that update the README on a schedule (recent activity, latest blog posts, Wakatime stats, etc.). Use when:

• The data being shown actually changes (Wakatime hours, latest blog post, recent commits across many repos).
• You can pin the action to a commit SHA (supply-chain hygiene — never pin to a moving tag).

Avoid when:

• The data is essentially static (your "currently working on" list rarely changes — write it by hand once a quarter).
• The action has fewer than ~50 stars OR a single maintainer. Pinned action SHA hashes still execute arbitrary code on every CI run.

Badges

Shields, hit counters, and stars-of-X services. See the dedicated "Badges" section above for the curated approach. The upstream catalog lists the providers; the rule above applies regardless of provider.

Miscellaneous

Trophies, joke generators, Spotify-now-playing, header image generators, programming-quote randomisers. Use when:

• You explicitly want a personal touch on a profile README (not a project README).
• The element doubles as a signal — e.g. a Spotify widget on a music-tech founder's profile reinforces their domain.

Avoid when:

• The misc element is the only personality in the README. If it is doing all the heavy lifting, the rest of the README is too thin.

Anti-patterns

The following are common and consistently make READMEs worse. Refuse or rewrite when you see them.

1. Badge bloat. More than ~7 badges crammed under the title. The eye sees a wall and skips it.
2. Emoji-padded section headers (## 🚀 Quick Start, ## ✨ Features). Distracting on desktop, broken on terminal viewers, and dates the doc. Use plain section titles.
3. Walls of text. Five-paragraph "Introduction" sections before the first code block. Readers want to know how to install it; they will read prose later if interested.
4. Dead-link demos. "Try the live demo!" pointing at a URL that 404s. Worse than no demo. Check links before committing.
5. Shields that link nowhere. A "MIT licensed" badge that points to nothing, or "Built with Love" with no anchor. Decorative shields are a tell.
6. Missing license. No LICENSE file and no SPDX identifier means default copyright applies — readers cannot legally use the code even if you intended otherwise.
7. Marketing copy without a quickstart. Three paragraphs about the vision, no code block in the first 500 words. Engineers bail.
8. Auto-generated stat cards that double-count. Stacking three different stat widgets that all show the same metric, in three different visualisations.
9. "Currently learning X" filler. Dates poorly and reads as inexperience. Write what you are working on, not what you are reading about.

Integration with sibling Walter-OS skills

The README is the artifact at the centre of a public release. It typically follows:

• brand-creation runs first if a new brand identity is needed. Logo + colour palette + voice doc inform the README's hero, badges, and tone.
• landing-page-fast runs if a marketing landing page is needed alongside. The README links to the landing; the landing links back to the README's quickstart. They are NOT the same artifact.
• oss-readiness runs as the gate before publishing. It audits the README among many other things; this skill is what the audit expects to find.
• content-writer is invoked separately for launch content (Twitter thread, blog post, newsletter). The README's "What" section is the seed for those longer pieces.
• frontend-quality does not directly apply, but the README's hero image / screenshots should respect the same image-optimisation rules: WebP / AVIF, lazy-loaded, alt text present.

Operator workflow

1. Decide the project type (project / profile / hackathon / OSS publish). One of the four templates above.
2. Draft the README from scratch — do not start from a generator. The blank page is faster than editing a bad first draft.
3. After draft: walk the anti-patterns list and remove any that applied.
4. Pick one statistical widget IF this is a profile README. Most widgets are served as SVG endpoints from a third-party host (raw.githubusercontent.com/..., github-readme-stats.vercel.app, etc.) — there is no commit SHA you can pin to. Supply-chain defense in this layer is therefore: (a) verify the upstream repo is actively maintained (commit within the last ~6 months), (b) prefer hosts the operator already trusts, (c) lock the widget's query string to a known-good config (so the rendered output does not silently change), and (d) re-audit on every quarterly upgrade pass. GitHub Actions that update the README on a schedule DO have pinnable SHAs — for those, follow the same supply-chain rule as any other action.
5. Curate badges. Drop anything that fails the "what question does this answer" test.
6. Add a hero artifact LAST — only after the core content is solid.
7. If the project is being published OSS: run oss-readiness to audit, then iterate.

Hard rules

• Never publish a README without an SPDX license identifier. A PR / commit that adds operator-facing public material with no license is incomplete.
• Pin pinnable upstream tools to commit SHAs — GitHub Actions and any tool you git clone or npm install. Use the same supply-chain rule as MCP servers. (Statistical-widget SVG endpoints are NOT pinnable; see "Operator workflow" step 4 for the alternative hardening — verify maintenance, trusted host, locked query string, quarterly re-audit.)
• Never embed widgets that require third-party tracking (visitor counters that log IPs, follower-history services that scrape on behalf of an authenticated user).
• Verify every external image link before commit. Dead images rendered as broken-image icons are worse than no image.

References

• Upstream catalog: dhyeythumar/awesome-readme-tools (CC0-1.0, public domain) — attribution: the 5-category structure used above (statistical widgets / generators / GitHub Actions / badges / miscellaneous) is the categorisation the upstream established.
• Sibling skills: landing-page-fast, brand-creation, oss-readiness, content-writer, frontend-quality.
• See also: tests/oss/depersonalization.bats for the OSS-readiness forbidden-token grep that any README this skill produces must pass.