samber/developer-relations-skills実行前に内容を確認
SKILL DETAIL
readme-optimization
samber/developer-relations-skills/readme-optimization
Audits and rewrites a repository README so a developer who has never seen the project can tell what it is, why it beats the alternative, and run the first command inside a minute - every claim and the documented install verified against the source, the page ordered into a bail-fast funnel, badges that earn nothing pruned. Use whenever someone says "review my README", "my readme is bad", "write a README for this repo", "nobody understands what my project does", "repo first impression", "readme structure", "too many badges", or is preparing an open-source launch - even if they only call it the repo landing page. Not a profile README - use samber/developer-relations-skills@github-profile-optimization.
インストール · 419出典を見る
Installation
npx skills add https://github.com/samber/developer-relations-skills --skill readme-optimization
スキルファイル
SKILL.md
最終同期 · 2026/10/23
evals/evals.json›
{
"skill_name": "readme-optimization",
"evals": [
{
"id": 1,
"prompt": "Hey - I maintain an OSS project called Tessarine, a Go library for fixed-point decimal money math, about 900 stars. I read somewhere that repos with detailed READMEs get 50% more contributions, and apparently that's GitHub's own research. So I want to go long: add an architecture section, a roadmap, an FAQ, and a contributors wall. Can you just rewrite the whole README now and make it detailed? Current one is 40 lines: title, a `go get` install block, three code samples, and an MIT line at the bottom.",
"expected_output": "A refusal to build on the cited statistic, an audit scorecard produced before any replacement prose, and a push back on padding the file with architecture, roadmap and FAQ sections.",
"files": [],
"expectations": [
"Identifies the '50% more contributions' figure as unsourced and states that the attribution to GitHub is invented",
"Declines to build the plan on that figure rather than repeating it or hedging around it",
"Does not promise any percentage lift in contributions, stars or installs as an outcome of the rewrite",
"Produces an audit scorecard before writing any replacement prose",
"Reports Band A as five pass/fail blocking checks and Band B as eight checks scored out of 16",
"Declares the target audience at the top of the scorecard before scoring anything",
"Pushes back on adding architecture, roadmap and FAQ sections, citing that half of sampled READMEs sit between 5 and 12 sections with a median of 7",
"States that padding a small single-purpose project makes it look abandoned rather than mature",
"Asks which project type and which audience the page serves before drafting prose",
"Attaches evidence to each check - a line reference, a quoted sentence, or the output of a command run - rather than asserting a verdict",
"Names a scarce content category (why-over-the-alternatives at 25.7%, or status at 21.4%) as a better use of added length than architecture or roadmap sections"
]
},
{
"id": 2,
"prompt": "Quick one. Repo is northgate-io/parqueue, a Python library for batching Parquet writes. GitHub Insights for the last 14 days says: 61 views, 34 unique visitors, 3 clones. We put it out five months ago and it's been flat ever since. My co-founder is convinced the README is the problem and wants it rewritten this week. Can you do the rewrite?",
"expected_output": "A diagnosis that the page is not the bottleneck at this traffic level, a routing to distribution or launch work instead of a rewrite, and the cheap repository furniture fixes offered anyway.",
"files": [],
"expectations": [
"Uses the given figures to state the clone-to-visitor ratio (3 of 34 unique visitors)",
"Identifies too few visitors, not weak prose, as the diagnosis - a distribution problem rather than a README problem",
"Declines to make the full rewrite the main recommendation for this repository",
"Routes the user toward launch or distribution work, naming samber/developer-relations-skills@oss-launch or samber/developer-relations-skills@oss-distribution-strategy",
"States that the few-percent clone-to-visitor boundary is a working heuristic rather than a benchmark",
"Recommends looking at referrers rather than ruling on a borderline number",
"Checks whether the README is the bottleneck before scoring or rewriting it",
"Does not promise a traffic or adoption increase from rewriting the page",
"Notes the code host's traffic data is a short rolling window of roughly two weeks and should be snapshotted rather than relied on retroactively",
"Still offers the repository furniture fixes - description, topics, website link, social preview - as the text that search listings and link unfurls actually carry"
]
},
{
"id": 3,
"prompt": "I've got one afternoon before a demo day on Friday. Repo: halyard-labs/streamsmith, a TypeScript CLI for replaying Kafka topics. The README has 11 badges, never says whether the project is maintained (it is, actively), an install block missing the Node version, a 'Why streamsmith' section that just says 'simple and fast', and the whole thing is in a strange order - install is at the very bottom. What do I fix first? Obviously the badges are the fastest thing to cut so I'll start there.",
"expected_output": "Three separate orderings with the efficiency one leading, the status line first rather than the badge row, and the funnel restructure named as what the ordering starves and dropped for the Friday date.",
"files": [],
"expectations": [
"States the fix ordering explicitly rather than leaving it implied by list order",
"Emits three separate orderings - effort, value, and efficiency - rather than one blended rank",
"Leads with the efficiency ordering (return per hour spent), not the effort ordering",
"Rejects starting with the badge row despite it being the cheapest edit to make",
"Places the status line first in the efficiency ordering",
"Explains that the status line and the badge row tie on effort but separate on value, citing that only 21.4% of READMEs state project status",
"Cites that 61% of contributors say badges do not influence them, as the reason the badge row ranks low on value",
"Names the funnel restructure as what the efficiency ordering starves",
"States the condition that promotes the funnel restructure anyway - a cold reader answering wrong because they never scrolled far enough, or a launch being the reason for the audit - and says the promotion goes against the ratio",
"Treats the Friday demo day as a hard date that promotes the fixes landing in an hour and drops the funnel restructure from this pass",
"Says which of the user's answers moved which fix in the ordering",
"Recommends a top-three first pass rather than working the full list"
]
},
{
"id": 4,
"prompt": "Pushback on your badge advice. I maintain corvid-dev/slotcache, a Rust crate with about 4,000 stars. My badge row is: build status, coverage 94%, crates.io version, docs.rs, downloads, MSRV, licence, 'PRs welcome', 'Made with Rust', contributor count, and Discord. I think badges make us look professional and serious, and every big project has them. Give me one reason to cut any of these.",
"expected_output": "The published badge evidence applied by name, the assessment/conventional split used to decide each badge, and the maintainer's over-valuation named rather than accepted.",
"files": [],
"expectations": [
"Cites Trockman et al. (ICSE 2018) and its scale of 294,941 npm packages",
"Applies the assessment-signal versus conventional-signal distinction by name",
"Classifies 'PRs welcome' and 'Made with Rust' as conventional signals and recommends cutting them",
"Keeps at least one assessment signal - CI status, coverage, published version, or dependency freshness - on the grounds that a third-party check backs it",
"States that adopting a badge does not raise popularity, and that popular projects are simply likelier to have badges",
"States that among already-popular packages excessive badge use correlates with decreased popularity",
"Notes this project's roughly 4,000 stars place it in the already-popular group that correlation applies to",
"Quotes the survey split: 88% of maintainers treat badge presence as a quality indicator against 53% of contributors",
"Names the maintainer's over-valuation of badges as the expected bias rather than accepting 'every big project has them'",
"Labels the cap of four badges as this skill's working default rather than a published figure",
"Justifies each surviving badge by the reader question it answers rather than arguing about the number",
"Notes that build-status badges mostly serve maintainers, who are better served by a failing-build notification"
]
},
{
"id": 5,
"prompt": "We shipped the README rewrite for aubergine-systems/tinshed last Tuesday. Leadership only cares about one number: GitHub stars. Set me up a tracking plan so I can show at next week's review that the rewrite worked - star count before and after, plus a star-history chart. I read that adding a star-history chart lifts star conversion about 15%, so let's put one in too.",
"expected_output": "Stars dropped from the tracking plan with the monotonicity reason, conversion rate offered instead, the cited 15% figure refused, and the one-week window replaced by a four-to-six-week re-measure.",
"files": [],
"expectations": [
"Drops stars from the tracking plan even though the user named stars as the goal",
"Explains that stars are cumulative and monotonic, so the metric cannot show a regression",
"Notes that stars would report success for a change that made the page worse",
"Offers conversion rate - clones or downloads divided by unique visitors - as the replacement metric",
"Identifies the '~15% star conversion lift from a star-history chart' claim as unsourced and declines to build on it",
"Ranks support load ahead of conversion rate and contributor conversion by efficiency, and states that ordering explicitly",
"Describes support load as counting the 'how do I install this' and 'what does this do' issues per month",
"Refuses the one-week review window, requiring re-measurement four to six weeks out because shorter windows are noise",
"Requires a full period before compared against a full period after, not a point-in-time snapshot on each side",
"States that attribution on a README is weak, and annotates confounders rather than claiming the delta",
"States that if clones rise but contributor count does not, the contribution path is broken rather than the README"
]
},
{
"id": 6,
"prompt": "fenwick-analytics/gridwarden is a self-hosted metrics store. It's AGPL-3.0 with a commercial exception you have to email us about. The README currently ends with '## License - AGPL-3.0, see LICENSE'. We get decent traffic, but a lot of people open an issue about three weeks in asking about licensing, after they've already deployed it. How should I structure the page?",
"expected_output": "The licence moved near the top on bail-fast grounds, cognitive funneling named and attributed, an A5 failure recorded, and the self-hosted-product skeleton chosen.",
"files": [],
"expectations": [
"Moves the licence statement near the top of the README rather than leaving it at the bottom",
"Justifies the move by how fast a non-permissive licence disqualifies a reader, not by convention or by tradition",
"Names cognitive funneling as the ordering principle and attributes it to Kira / Art of README",
"States the principle as widest and most disqualifying information first, narrowing to detail only a committed reader reaches",
"Treats a reader deciding not to use the project as a correct outcome rather than a conversion to optimize away",
"Scores the current state as an A5 failure and notes it fails harder because the licence is non-permissive and buried",
"Cites that 64% of respondents to GitHub's 2017 Open Source Survey called the licence very important in deciding whether to use a project",
"Requires the licence file to ship inside the repository, noting an organization-level default is not enough",
"Surfaces the commercial exception and its email step in the README rather than leaving it to be discovered later",
"Ties the three-weeks-in licensing issues to a specific scorecard check as evidence the page wastes readers' time",
"Selects the application or self-hosted product skeleton rather than the library ordering, because the reader is deciding whether to run infrastructure"
]
},
{
"id": 7,
"prompt": "Here's the section list for quillmark/parsely, a Java library for streaming CSV: 1 Title plus logo, 2 Table of Contents (hand-written, 22 entries), 3 Installation (Maven and Gradle), 4 Quick Start, 5 Full API Reference (all 61 public methods), 6 Configuration options table (40 rows), 7 Contributing (our whole dev-env setup, about 80 lines), 8 Code of Conduct (full Contributor Covenant text inline), 9 Security policy, 10 Changelog (every release since 2021), 11 Credits, 12 License. It's 1,400 lines. Trim it for me.",
"expected_output": "Usage moved above install for a library, the hand-written TOC deleted, community health and reference content relocated to their conventional files with one-line pointers, and the two scarce sections added.",
"files": [],
"expectations": [
"Reorders so the usage example appears above the install section for this library",
"Justifies usage-above-install by the reader who dislikes the API shape not caring how to install it",
"Deletes the hand-written table of contents and states that code hosts generate an outline from headings",
"Moves the contributing content to CONTRIBUTING.md and leaves a one-line pointer behind",
"Moves the code of conduct to CODE_OF_CONDUCT.md and leaves a one-line pointer behind",
"Moves the security policy to SECURITY.md and leaves a one-line pointer behind",
"Moves the release history to CHANGELOG.md and leaves a one-line pointer behind",
"Moves the full API reference and the 40-row configuration table to a documentation site or generated reference",
"States that overflow is relocated, never deleted",
"Keeps the licence file inside the repository even while the other community health files move out",
"Names the median of 7 sections and the 5-to-12 band as the size signal this file misses",
"Adds a differentiation section, noting that only 25.7% of READMEs carry any why-over-the-alternatives content"
]
},
{
"id": 8,
"prompt": "Audit this README for petrichor-cli/haze please. You can read the repo files, but this environment has no shell so you can't execute anything. The relevant lines are: 'Install: `pip install haze`'. 'haze handles 10k requests/sec on a laptop.' 'Use `--watch` to re-run on file change.' 'Works on Python 3.8+.' 'Automatically reconnects when the upstream drops.' 'Case-insensitive by default.' Tell me whether it passes.",
"expected_output": "A refusal to mark the install check passed on inspection, an explicit request for the user to run the sequence from clean, and each claim routed to its own source of truth in the repository.",
"files": [],
"expectations": [
"Refuses to mark the install check (A2) as passed on inspection alone",
"States plainly that commands cannot be executed here and asks the user to run the documented sequence and paste the output",
"Specifies starting from a clean state - a container, a fresh virtual environment, or a temporary directory",
"Requires running the install command and then the first usage example exactly as written",
"Treats 'automatically reconnects' and 'case-insensitive by default' as behavioural claims to verify rather than as prose",
"Checks `--watch` against the argument parser and calls an absent flag a hallucination rather than a typo",
"Requires a benchmark script, CI matrix or changelog entry inside the repository behind the '10k requests/sec' claim, or the claim comes out",
"Checks 'Python 3.8+' against the package manifest rather than accepting it as written",
"Reports the count of unverifiable claims on its own line of the scorecard",
"Downgrades any claim it cannot verify to what it can verify, and says which part is unconfirmed",
"Declines to issue an overall pass verdict while a blocking Band A check is unresolved"
]
},
{
"id": 9,
"prompt": "brightmoor/ledgerlink is an open-source double-entry ledger written in Go. Two banks and an insurer are evaluating us right now and their security teams are asking questions. Our board thinks we should donate the project to a foundation this quarter so we look credible. We have four maintainers, all employed by us, releases roughly monthly, and no SECURITY.md. What should the README say?",
"expected_output": "The six enterprise trust signals ranked on three axes, the cheap first three recommended for this quarter, and the foundation decision flagged as irreversible and handed to the user.",
"files": [],
"expectations": [
"Confirms the declared audience is a company or procurement evaluator and runs the enterprise trust-signal step on that basis",
"Lists all six available trust signals rather than a subset",
"Emits separate effort, value and compliance-cost orderings for the six signals",
"Places foundation affiliation highest on value and lowest on efficiency",
"Recommends the first three - support expectation, release cadence, security policy - as the default, roughly an afternoon between them",
"Writes the release cadence and support expectation from what is already true, needing nobody's permission",
"Names foundation affiliation as what the efficiency ordering starves",
"States the promote condition for foundation affiliation: the project is being adopted as infrastructure rather than as a dependency, or a foundation tier is the objection repeatedly lost to",
"Flags the foundation decision's irreversibility - trademark or IP assignment and a legal sign-off that cannot be walked back - and hands that decision to the user rather than making it",
"Warns that a published security policy commits the project publicly to a response window it then has to honour",
"Notes that all four maintainers share one employer, so maintainer depth and employer diversity is a signal these evaluators will check",
"States that published evaluation checklists weight maintenance activity, licence clarity and security posture above presentation quality"
]
},
{
"id": 10,
"prompt": "Tiny thing: ferrous-nine/bitrune, a Rust crate that does one job - parse and re-emit ULID strings. About 200 lines of code. It's just me, weekends only, and I have zero appetite for anything legal or ongoing. The current README is title, install, one example, licence - four sections. A friend said it looks unserious and that I should add architecture, a roadmap, a governance section, a security policy, and a demo GIF. Fix it up?",
"expected_output": "Confirmation that four sections is complete here, with every ruled-out item deleted rather than parked, and an honest solo support expectation in place of governance theatre.",
"files": [],
"expectations": [
"Confirms that a four-section README is complete for a single-purpose project of this size",
"States that adding architecture and roadmap sections to a small utility makes it look abandoned rather than mature",
"Deletes the demo outright rather than parking it as future work, because a library with no visible output earns nothing from one",
"Deletes the governance heading rather than listing it as a later improvement",
"Deletes the enterprise trust signals, because no company or procurement audience was declared",
"Explains that ruled-out fixes are deleted rather than demoted, since an item parked at the bottom silently reappears as scope",
"Writes an honest support expectation - solo maintainer, weekends only - instead of an empty governance section",
"Asks for or states the effort ceiling before ranking anything",
"Recommends a status line stating the project is maintained solo and at what pace",
"Keeps a line naming what the crate deliberately does not do and when to use something else",
"Does not recommend a security policy, since it would commit a weekend maintainer to a response window"
]
},
{
"id": 11,
"prompt": "stagline/toolbelt is a Python monorepo - six packages, four of which we publish to PyPI. We have both a .github/README.md and a root README.md and I think they've drifted apart. The root one embeds `` and a `<details><summary>` block with the config table inside it, plus a 6MB demo GIF right at the top showing the CLI in use. On GitHub it looks great. Can you check it over?",
"expected_output": "The shadowed copy resolved in favour of the root file, the registry render audited as its own target with absolute paths, and the monorepo root turned into a router.",
"files": [],
"expectations": [
"Flags the shadowed copy: only one README is rendered, and the other silently diverges",
"States that the root README is what package registries and mirrors publish, so it is the copy to keep",
"Recommends keeping exactly one rendered README rather than syncing the two files",
"States that relative image and link paths break on the PyPI page because the registry renders the README on its own domain",
"Recommends converting relative paths to absolute URLs, for example raw.githubusercontent.com, at publish time",
"Flags the raw HTML `<details>` block as registry-hostile, since the config table inside it disappears where HTML is stripped",
"Requires auditing the registry render as a separate target, noting it often carries more traffic than the code host render",
"Requires alt text on the architecture image",
"States that no instruction, command or decision-relevant fact may live only inside the GIF, because it is invisible in terminals, on registry pages, and to screen readers",
"Flags the GIF's page weight as a real cost independent of any conversion argument",
"Makes the monorepo root README a router to the per-package READMEs rather than covering all six inline",
"Recommends generating the demo from a script - a diffable, re-renderable tape or cast file - rather than hand-recording it, so it survives output changes"
]
},
{
"id": 12,
"prompt": "Just need the top of the README rewritten, nothing else. Project is oaklight/prismstore, an embedded key-value store in Zig built on an LSM tree. Give me the title line and the opening two sentences. Make it punchy - something like 'Prismstore is a blazing-fast, developer-friendly embedded database. Production ready and battle-tested.' That's the vibe. We've been running it internally for four months.",
"expected_output": "Three candidate one-liners on the three named axes with trade-offs and a recommendation, the fabricated status and unfalsifiable adjectives refused, and a humanizer pass before presenting.",
"files": [],
"expectations": [
"Drafts three candidate one-liners rather than a single phrasing",
"Builds the three candidates on the three named axes: what it does mechanically, what problem it removes, and what it lets you stop using",
"Presents each candidate's trade-off alongside a recommendation and leaves the final choice to the user",
"Refuses 'production ready' and 'battle-tested' as fabricated status that one glance at the commit history disproves",
"Refuses 'blazing fast' and 'developer-friendly' as unfalsifiable, replacing them with something checkable - a number, a dependency count, a supported-platform list, or a named trade-off",
"Proposes an honest status statement matching four months of internal use rather than a maturity claim",
"Notes that the one-liner propagates into the repository description, the registry page, and every link unfurl",
"Names the technology, the job and the runtime or platform constraint inside the opening sentences",
"Runs the finished prose through a humanizer pass before presenting it",
"States that superlatives without evidence lower trust with a developer audience",
"Gets agreement on this section before moving on to any other"
]
},
{
"id": 13,
"prompt": "Our README is the problem. New devs at cinderpath/relaykit, a Node SDK, can't get from zero to a working call - it takes them three days. Our docs site is 140 pages of chaos with no structure. And nobody ever opens a PR. I want you to expand the README into a proper end-to-end tutorial, add the full docs table of contents to it, and paste our contribution process in there too, so everything's in one place.",
"expected_output": "A refusal to stretch the README over three different jobs, with each routed to the right sibling skill and the README kept to the page plus its repository furniture.",
"files": [],
"expectations": [
"Declines to expand the README into a tutorial, a docs index, and a contribution guide",
"States that a README is a landing page and a router, not a documentation type, judged on whether it converts a visitor into a trial",
"Routes the zero-to-working-call problem to samber/developer-relations-skills@developer-quickstart-guide",
"Routes the 140-page docs site to samber/developer-relations-skills@developer-docs-structure-audit",
"Routes the contribution path to samber/developer-relations-skills@oss-contributor-onboarding",
"States that Diataxis classifies documentation into tutorial, how-to, reference and explanation, and that a README is none of the four",
"States that Diataxis governs the docs site's structure rather than the README's internal order",
"Keeps the README's scope to the page and its repository furniture - description, website link, topics, social preview",
"Leaves a one-line pointer in the README to each relocated destination rather than dropping the link entirely",
"Identifies which of the three problems the README can actually move, and says plainly that the other two need different work"
]
},
{
"id": 14,
"prompt": "ambervale/dtx is a terminal tool that diffs two Terraform plans and colour-codes the drift. The whole value is what the output looks like. I've got maybe a week. The repo has no description set, no topics, the website field is empty, and the social preview is still the default. The README is plain text with no images. Where does the effort go?",
"expected_output": "The step's default ordering stated, then the demo deliberately promoted above render mechanics because the output is the product, with furniture still done first and the demo script-generated.",
"files": [],
"expectations": [
"States the default ordering for this step out loud: furniture, then render mechanics, then terminal demo",
"Promotes the terminal demo above render mechanics for this project, and says explicitly that it is because the output is the product for a CLI",
"Says the promotion is a deliberate departure from the default ordering",
"Fixes the repository furniture first: description, website link, topics, and social preview",
"Explains that furniture is what search listings carry and what unfurls when the link is pasted into a chat",
"Prices the demo at roughly a week, and warns it becomes a standing job that goes stale when the output changes",
"Requires generating the demo from a script so that re-rendering stays cheap",
"Places the demo immediately after the tagline",
"Requires the demo to be short, high-contrast and legible at embed scale",
"Requires the commands shown in the demo to also appear as copyable text, since a reader on a registry page or in a terminal sees nothing",
"Selects the CLI skeleton, leading with a real terminal transcript and then why this over the incumbent tool, with per-platform package-manager one-liners in the install section"
]
},
{
"id": 15,
"prompt": "Done - we rewrote the README for salterfell/cogwheel over the weekend, and ran it through a README health-score tool that gave it 92/100, grade A. Install works, the licence is linked, and the status line says 'actively maintained'. Ship it?",
"expected_output": "The tool score rejected as evidence of persuasion, the full scorecard re-run against the stated thresholds, and the cold-reader test specified with its protocol and check mapping.",
"files": [],
"expectations": [
"Declines to accept the 92/100 tool score as evidence that the README works",
"States that structural scorers measure form, hygiene or complexity rather than whether a reader was persuaded, so a high score is compatible with a README nobody understands",
"Re-runs the full scorecard rather than spot-checking the three items the user listed",
"Requires all five Band A checks to pass and Band B to total at least 14 of 16",
"Labels the 14-of-16 bar as this skill's own default rather than a published standard, movable by the user for a stated reason recorded in the report",
"Runs the cold-reader test with a reader who has never seen the project - a person if one can be found, otherwise a fresh agent session with no repository context",
"Specifies the cold-reader protocol: five questions, a 60-second window, and five correct answers to pass",
"Lists the five questions, including why to use it instead of the alternative the reader already knows, and whether the project is alive",
"Maps a wrong answer to a specific check - question 2 to B1, question 5 to A4",
"Labels the 60-second window, the five questions and the five-of-five bar as this skill's own construction rather than a published protocol"
]
}
],
"trigger_queries": [
{ "query": "review my README", "should_trigger": true },
{ "query": "my readme is bad, can you fix it", "should_trigger": true },
{ "query": "write a README for this repo", "should_trigger": true },
{ "query": "nobody understands what my project does", "should_trigger": true },
{ "query": "repo first impression", "should_trigger": true },
{ "query": "readme structure", "should_trigger": true },
{ "query": "too many badges", "should_trigger": true },
{ "query": "audit the README of this repo", "should_trigger": true },
{ "query": "our GitHub gets traffic but no installs", "should_trigger": true },
{ "query": "rewrite the top of our README before launch", "should_trigger": true },
{ "query": "make our README readable by someone evaluating us for their company", "should_trigger": true },
{ "query": "can you look at our repo landing page", "should_trigger": true },
{ "query": "what should the first two lines of my repo page say", "should_trigger": true },
{ "query": "people star the repo but never install it", "should_trigger": true },
{ "query": "our repo page hasn't been touched in two years, is it still okay", "should_trigger": true },
{ "query": "how many badges is too many", "should_trigger": true },
{ "query": "should install go before or after the usage example", "should_trigger": true },
{ "query": "where does the licence go on the page", "should_trigger": true },
{ "query": "my project page is a wall of badges and a giant logo", "should_trigger": true },
{ "query": "readme audit", "should_trigger": true },
{ "query": "score my README", "should_trigger": true },
{ "query": "is my README any good", "should_trigger": true },
{ "query": "help me write the opening paragraph for my open source project page", "should_trigger": true },
{ "query": "we need a one-liner for the repo", "should_trigger": true },
{ "query": "what goes at the top of a repo page", "should_trigger": true },
{ "query": "our npm package page looks broken but GitHub looks fine", "should_trigger": true },
{ "query": "the images in my README don't show up on PyPI", "should_trigger": true },
{ "query": "how do I say why someone should use my library instead of the popular one", "should_trigger": true },
{ "query": "developers land on our repo and leave", "should_trigger": true },
{ "query": "readme conversion", "should_trigger": true },
{ "query": "how long should a README be", "should_trigger": true },
{ "query": "I have both a .github/README.md and a root README.md, does it matter", "should_trigger": true },
{ "query": "our README documents a bunch of flags I don't think exist anymore", "should_trigger": true },
{ "query": "the install instructions in our README are wrong", "should_trigger": true },
{ "query": "can you check whether the commands in our README still work", "should_trigger": true },
{ "query": "should I add a demo GIF to the repo", "should_trigger": true },
{ "query": "how do I make my repo look maintained", "should_trigger": true },
{ "query": "we're open sourcing next month and the repo page needs work", "should_trigger": true },
{ "query": "prep the repository page for launch day", "should_trigger": true },
{ "query": "enterprise buyers are looking at our repo, what do they need to see there", "should_trigger": true },
{ "query": "security reviewers bounce off our repo page", "should_trigger": true },
{ "query": "the page doesn't say whether the project is alive", "should_trigger": true },
{ "query": "how do I show project status without lying about it", "should_trigger": true },
{ "query": "trim our README, it's 1500 lines", "should_trigger": true },
{ "query": "should the contributing guide be inside the README", "should_trigger": true },
{ "query": "do I need a table of contents in my README", "should_trigger": true },
{ "query": "what sections does a CLI tool's repo page need", "should_trigger": true },
{ "query": "what should a library's repo page look like versus a framework's", "should_trigger": true },
{ "query": "I want a stranger to understand the project in 30 seconds", "should_trigger": true },
{ "query": "cold read my project page and tell me what's confusing", "should_trigger": true },
{ "query": "first-time visitor experience on our GitHub repo", "should_trigger": true },
{ "query": "fix the ordering of sections on our repo page", "should_trigger": true },
{ "query": "our repo page buries the install command at the bottom", "should_trigger": true },
{ "query": "readme rewrite", "should_trigger": true },
{ "query": "markdown landing page for the repository", "should_trigger": true },
{ "query": "how do I differentiate my project on its repo page", "should_trigger": true },
{ "query": "the repo description and topics are empty, does that matter", "should_trigger": true },
{ "query": "what shows up when someone pastes our repo link into Slack", "should_trigger": true },
{ "query": "social preview image for the repo", "should_trigger": true },
{ "query": "the README says production ready but honestly it isn't", "should_trigger": true },
{ "query": "can you make the README less markety", "should_trigger": true },
{ "query": "our README reads like it was generated", "should_trigger": true },
{ "query": "how do I stop people opening issues asking what the project does", "should_trigger": true },
{ "query": "we get the same install question over and over", "should_trigger": true },
{ "query": "monorepo with six packages, how do I organise the top-level readme", "should_trigger": true },
{ "query": "does anyone actually read badges", "should_trigger": true },
{ "query": "should I keep the coverage badge", "should_trigger": true },
{ "query": "my co-maintainer thinks the README is fine, I don't, settle it", "should_trigger": true },
{ "query": "what do I fix first on the repo page, I have one afternoon", "should_trigger": true },
{ "query": "how do I measure whether the readme rewrite worked", "should_trigger": true },
{ "query": "track whether our repo page changes did anything", "should_trigger": true },
{ "query": "how do I check my README renders correctly everywhere", "should_trigger": true },
{ "query": "screen reader accessibility of a repository landing page", "should_trigger": true },
{ "query": "our README has no alt text on anything", "should_trigger": true },
{ "query": "the project page never mentions the licence", "should_trigger": true },
{ "query": "how do I write the 'why use this' section without trashing competitors", "should_trigger": true },
{ "query": "optimize my GitHub profile README", "should_trigger": false },
{ "query": "what should I pin on my GitHub profile", "should_trigger": false },
{ "query": "my personal GitHub bio and social links need work", "should_trigger": false },
{ "query": "set up an organization profile repository", "should_trigger": false },
{ "query": "my contribution graph looks empty, does that hurt me", "should_trigger": false },
{ "query": "write a quickstart page for our API", "should_trigger": false },
{ "query": "our time to first hello world is 40 minutes", "should_trigger": false },
{ "query": "our getting-started page needs a rewrite", "should_trigger": false },
{ "query": "what should the fail branches in a quickstart say", "should_trigger": false },
{ "query": "write a build-along tutorial for our SDK", "should_trigger": false },
{ "query": "how many new concepts per tutorial step", "should_trigger": false },
{ "query": "audit our docs site information architecture", "should_trigger": false },
{ "query": "classify our documentation pages against Diataxis", "should_trigger": false },
{ "query": "our docs navigation doesn't match our file tree", "should_trigger": false },
{ "query": "canonical tags across our versioned docs", "should_trigger": false },
{ "query": "our documentation pages aren't getting indexed", "should_trigger": false },
{ "query": "half our docs code samples no longer compile", "should_trigger": false },
{ "query": "define a policy for code snippets in documentation", "should_trigger": false },
{ "query": "turn these 80 commits into release notes", "should_trigger": false },
{ "query": "write the GitHub release body for v3.0.0", "should_trigger": false },
{ "query": "our CHANGELOG.md is unreadable", "should_trigger": false },
{ "query": "write the v2 to v3 migration guide", "should_trigger": false },
{ "query": "document what breaks in the next major release", "should_trigger": false },
{ "query": "write our CONTRIBUTING.md", "should_trigger": false },
{ "query": "nobody makes a second contribution after their first PR", "should_trigger": false },
{ "query": "set up a good-first-issue queue", "should_trigger": false },
{ "query": "plan our Show HN launch", "should_trigger": false },
{ "query": "how do we get onto GitHub Trending", "should_trigger": false },
{ "query": "launch day war room plan", "should_trigger": false },
{ "query": "which curated awesome lists should we get our project onto", "should_trigger": false },
{ "query": "package registry metadata and distribution strategy", "should_trigger": false },
{ "query": "should we go Apache 2.0 or MPL", "should_trigger": false },
{ "query": "do we need a CLA or a DCO", "should_trigger": false },
{ "query": "write our project governance document", "should_trigger": false },
{ "query": "how do maintainers get promoted in our project", "should_trigger": false },
{ "query": "design our issue triage rotation", "should_trigger": false },
{ "query": "our issue tracker has 900 open issues", "should_trigger": false },
{ "query": "write our CODE_OF_CONDUCT.md", "should_trigger": false },
{ "query": "design the moderation escalation ladder for our Discord", "should_trigger": false },
{ "query": "write our SECURITY.md vulnerability disclosure process", "should_trigger": false },
{ "query": "set up GitHub Sponsors tiers for my project", "should_trigger": false },
{ "query": "write our FUNDING.yml sponsor pitch", "should_trigger": false },
{ "query": "which open source projects should our company fund", "should_trigger": false },
{ "query": "write a how-we-built-it engineering blog post", "should_trigger": false },
{ "query": "our engineering blog reads like marketing", "should_trigger": false },
{ "query": "turn this customer deployment into a technical case study", "should_trigger": false },
{ "query": "make our docs something a coding agent can integrate from unattended", "should_trigger": false },
{ "query": "do we need an llms.txt file", "should_trigger": false },
{ "query": "which error strings do developers actually search for", "should_trigger": false },
{ "query": "which DevRel KPIs should we report to the board", "should_trigger": false },
{ "query": "build our devrel tracking plan and event taxonomy", "should_trigger": false },
{ "query": "benchmark our competitor's developer experience", "should_trigger": false },
{ "query": "cut our developer audience into named segments", "should_trigger": false },
{ "query": "map the developer journey from discovery to advocacy", "should_trigger": false },
{ "query": "my live demo keeps breaking on stage", "should_trigger": false },
{ "query": "turn my accepted abstract into a talk outline", "should_trigger": false },
{ "query": "write my conference CFP submission", "should_trigger": false },
{ "query": "write the script for a five-minute screencast", "should_trigger": false },
{ "query": "prep me for a podcast interview next week", "should_trigger": false },
{ "query": "how much should I share publicly while building", "should_trigger": false },
{ "query": "design an unpaid ambassador program", "should_trigger": false },
{ "query": "should we start a Discord for our users", "should_trigger": false },
{ "query": "start a monthly user group in Lisbon", "should_trigger": false },
{ "query": "which conferences should we sponsor this year", "should_trigger": false },
{ "query": "pick the value metric for our developer tool's pricing", "should_trigger": false },
{ "query": "open core or hosted open source", "should_trigger": false },
{ "query": "design the bottom-up self-serve motion for our developer product", "should_trigger": false },
{ "query": "should our product become a platform", "should_trigger": false },
{ "query": "should we build a certification program", "should_trigger": false },
{ "query": "write the job posting for a developer advocate", "should_trigger": false },
{ "query": "how do I break into DevRel", "should_trigger": false },
{ "query": "pitch this release to reporters", "should_trigger": false },
{ "query": "translate our README into Japanese and Portuguese", "should_trigger": false },
{ "query": "generate a README scaffold from a JSON config template", "should_trigger": false },
{ "query": "index every README in our monorepo into a search index", "should_trigger": false },
{ "query": "our docs site landing page needs a hero section and a CTA", "should_trigger": false }
]
}
references/audit-scorecard.md›
# README audit scorecard
Score the README as it exists today, before proposing any rewrite. Report every check with the evidence that decided it - a line number, a quoted sentence, or a command you ran. A check with no evidence is an opinion, and the user is entitled to reject it.
State the declared audience - solo developer, company or procurement evaluator, or both - on the first line of the report. Several checks resolve differently depending on it, so a scorecard with no declared audience cannot be audited by anyone else.
## Band A - blocking checks
Each is pass or fail. A single failure means the README is not fit to publish, whatever the rest scores.
**A1 - Identity in the first two lines.** The project name and one sentence saying what it is appear before anything else a reader must scroll past. Every unusual term in that sentence is either defined inline or linked. Fail if the first thing under the title is a badge wall, a logo the size of a screen, or a sentence that only makes sense to someone who already uses the project.
**A2 - The first command runs.** Take the install command and the first usage example exactly as written, run them in a clean environment, and record what happens. Fail on any undocumented prerequisite, any command that errors, any output that contradicts the README. This is the check that catches the most real damage, because a reader who hits a broken install leaves and does not file an issue.
**A3 - Every claim is verifiable.** List every command, flag, default, environment variable, config key, endpoint, exported symbol, file path, version requirement, and behavioural assertion in the file, then check each against its own source of truth in the repository - the argument parser, the definition site, the route table, the changelog. Fail on any documented flag the parser does not register, any signature that does not match, and any performance number, compatibility matrix or scale claim with no benchmark, CI matrix or changelog entry behind it. Report the count of unverifiable claims on its own line, because it is the finding maintainers most often dispute and most often lose.
**A4 - Status is stated honestly.** A reader can tell whether the project is experimental, actively maintained, feature-frozen, or looking for a new maintainer, without opening the commit history. Fail if the README implies more stability than the project has. Only 21.4% of READMEs carry status content at all (Prana et al. 2019), so stating it is both rare and cheap.
**A5 - Licence is reachable from the README.** Named in the README, linked to the file. Fail if a reader has to guess, and fail harder if the licence is non-permissive and buried at the bottom; that is the fastest disqualifier for a commercial reader, so it belongs near the top where it saves their time. 64% of respondents to GitHub's 2017 Open Source Survey called the licence very important in deciding whether to use a project, the highest-rated documentation element in that survey.
## Band B - scored checks
Score each 0, 1, or 2. Zero means absent, one means present but weak, two means it does its job.
**B1 - Differentiation.** The README says why to choose this over the obvious alternative, in the project's own words, without disparaging anyone. This is the scarcest content category measured - only 25.7% of READMEs have any (Prana et al. 2019) - so it is usually the highest-leverage check on the board.
- 2 points: a concrete axis - a benchmark, a dependency count, a supported-platform difference, a design trade-off deliberately taken.
- 1 point: a vague "simple and fast".
**B2 - Time to a copyable command.** A command the reader can paste appears within roughly the first screen.
- 2 points: inside the first 400 words.
- 1 point: arrives after a long preamble.
- 0 points: no code block at all.
**B3 - Runnable usage example.** The example is real code a reader could execute, and it shows the output or the effect. Two points if the same snippet also exists as a file in the repository. Zero for a bare list of function signatures; that is API reference material, not usage.
**B4 - Funnel ordering.** Sections are ordered so a reader can disqualify the project as early as possible: identity, then differentiation, then usage, then install, then detail, then background. Two points if a reader can stop at any point without having missed something that would have changed their decision.
**B5 - Badge discipline.** Each badge should be an assessment signal answering a question a visiting reader actually has: is it maintained, what version, what licence, does it work on my platform.
- 2 points: four badges or fewer.
- 1 point: a tolerable row.
- 0 points: a badge wall, or a row built on conventional signals such as "PRs welcome".
Trockman et al. (ICSE 2018, 294,941 npm packages) found that adopting badges does not raise popularity, and that among already-popular packages excessive badge use correlates with decreased popularity; the _direction_ is sourced, the cap of four is this skill's own baseline. Build-status badges mostly serve maintainers, who are better served by a failing-build notification.
**B6 - Nothing critical trapped in an image.** Every image has alt text, and no instruction, command, or decision-relevant fact exists only inside a screenshot, diagram, or animated demo. Readers meet READMEs in terminals, in package-registry pages that strip HTML, and through screen readers.
**B7 - Links resolve everywhere.** Relative links resolve on the default branch, and the README still makes sense when rendered on the package registry page, where relative paths and raw HTML often break. Two points requires actually checking the registry render, not assuming it. Confirmed on both npm and PyPI: both registries render the README on their own domain rather than the source repository's, so a relative image or link path that works on the code host resolves to a dead link on the registry page - PyPI in particular has no support for relative image paths at all, and the standard fix is converting to absolute URLs (e.g. `raw.githubusercontent.com`) at publish time.
**B8 - Overflow lives elsewhere.** Long reference material, tutorials, configuration tables, and community health content (contributing, code of conduct, security policy, support) are linked, not inlined. Half of all sampled READMEs sit between 5 and 12 sections with a median of 7 (Prana et al. 2019), so a count in that band is the normal signal; more is fine when the project genuinely has that many top-level concerns, but say why.
## Pass threshold
The README passes when all five Band A checks pass **and** Band B totals **14 of 16 or more**.
**This threshold is this skill's own baseline, not a published standard.** The automated README scorers in the field measure structural proxies rather than persuasion. Treat 14/16 as the default and let the user move it for a stated reason.
Below the threshold, rewrite and re-score rather than shipping with a note. Iterate until it is met or the user explicitly accepts a lower score for a stated reason; record that reason in the report so the next reviewer does not relitigate it.
## The cold-reader test
Run this after the rewrite, as the outcome check that the scorecard is only a proxy for.
Give the README to a reader who has never seen the project - a person if the user can find one, otherwise a fresh agent session with no repository context. Allow 60 seconds, from the top, no scrolling past the fold more than once. Ask five questions:
1. What is this?
2. Why would I use it instead of the alternative I already know?
3. Does it fit my language, platform, and licence constraints?
4. What is the first command I would run?
5. Is this project alive?
Pass is five correct answers within the minute. The 60-second window, the five questions, and the five-of-five bar are this skill's own construction, like the 14/16 threshold - not a published protocol - move them with the user for a stated reason. Anything less than a pass points at a specific check, which makes the failure directly actionable: a wrong answer to question 2 is a B1 problem, to question 5 an A4 problem.
## Reporting format
```
README audit ; acme/flowmatic (audience: solo developer)
Band A: A1 pass · A2 FAIL (npm install needs Node >=20, undocumented) · A3 FAIL · A4 pass · A5 pass
Claim check: 2 unverifiable ; "handles 10k req/s" (no benchmark in repo), --watch flag not in parser
Band B: 11/16 (B1 0, B2 2, B3 1, B4 2, B5 0, B6 2, B7 2, B8 2)
Verdict: does not pass ; A2 and A3 blocking; B1 returns the most per hour spent
Cold-reader test: 3/5 ; readers could not answer "why this over X" or "is it alive"
Fix in this order:
1. Document the Node version requirement and re-run the install from clean (A2)
2. Remove or source the throughput claim; drop --watch from the docs (A3)
3. Add three sentences on why this over <alternative> (B1)
4. Cut the badge row from 9 to 3 (B5)
```
The fix list is ordered by return per hour spent, using the ordering in SKILL.md § Order the fixes, and re-ranked against the user's deadline and effort ceiling. Say in the report which of their answers moved which fix.
For an enterprise or procurement audience, add one line listing which trust signals are present and which are missing, in the order SKILL.md § Step 8 ranks them:
`support expectation == release cadence > security policy > named adopters > governance and maintainer depth > supply-chain attestation > foundation affiliation`
That line doubles as the order to fix them in. Those are not scored; they are pass/absent facts a buyer will check anyway.
references/before-after-examples.md›
# Worked examples
Positive examples are quoted from real published READMEs and attributed. Negative examples are constructed anti-patterns - they are composites of common failures, not quotations of any real project, and should never be attributed to anyone.
## Table of Contents
- [The opening lines](#the-opening-lines)
- [Stating why over the alternative](#stating-why-over-the-alternative)
- [Stating project status](#stating-project-status)
- [The badge row](#the-badge-row)
- [The install section](#the-install-section)
- [The usage example](#the-usage-example)
## The opening lines
**Good** - `d3/d3`'s published opening:
> **D3** (or **D3.js**) is a JavaScript library for visualizing data using web standards. D3 helps you bring data to life using SVG, Canvas and HTML.
It names the technology, the job, and the medium in two sentences. A reader who does not work in the browser leaves immediately, which is the correct outcome for both parties.
**Good** - `jmilleralpine/ParallelGit`'s published opening:
> A high performance Java JDK 7 nio in-memory filesystem for Git.
Fourteen words carrying language, runtime requirement, mechanism, and purpose.
**Bad** - constructed:
> # flowmatic
>
> [badge][badge][badge][badge][badge][badge][badge]
>
> <img src="logo.png" width="700">
>
> Flowmatic makes it easy to work with flows. Built with ❤️ and TypeScript.
The reader is four scrolls in and still does not know what a "flow" is. "Makes it easy" says nothing measurable, and the logo pushes the only informative sentence below the fold.
## Stating why over the alternative
**Bad** - constructed:
> ## Why flowmatic?
>
> Flowmatic is simple, fast, lightweight and developer-friendly.
Every project claims this, so it carries no information and costs a section.
**Better** - constructed, showing the shape to aim for:
> ## Why flowmatic
>
> Use it when you need retries and backoff but not a scheduler. It has no runtime dependencies and adds about 12 kB gzipped, against roughly 300 kB for a full workflow engine. If you need cron scheduling, durable state across restarts, or a UI, use a workflow engine instead - flowmatic deliberately has none of those.
Concrete axes, a number the reader can verify, and an explicit statement of when _not_ to use it. Naming the case against your own project is the fastest way to earn a developer's trust, and it filters out the users who would have churned anyway.
## Stating project status
**Better** - constructed:
> Flowmatic is in early beta. Retry and backoff are stable; scheduling and durable state are not built yet. That said, we run it ourselves every day, and we'd rather you find the rough edges than we find them for you.
Honest about maturity, specific about the risk, and still gives a reason to try it.
**Bad** - constructed:
> ## Status
>
> Production ready! 🎉
Unfalsifiable, and contradicted the moment a reader checks the issue tracker.
## The badge row
**Bad** - constructed: nine badges covering build status, coverage, three package registries, licence, contributor count, chat, and "made with love".
Ask of each one: what decision does a first-time visitor make with this? Coverage percentage and contributor count almost never change an adoption decision. Build status tells the reader the maintainers' CI is red, which is information for the maintainers.
**Good** - four badges: latest released version, licence, supported runtime versions, and last-release date or maintenance status. Each answers a question from the cold-reader test.
## The install section
**Bad** - constructed:
> ## Installation
>
> ```
> npm install flowmatic
> ```
No runtime constraint, no import line, no verification step. This is the single most common cause of a blocking A2 failure in the scorecard.
**Better** - constructed:
> ## Install
>
> Requires Node 20 or later.
>
> ```bash
> npm install flowmatic
> ```
>
> Verify:
>
> ```bash
> node -e "console.log(require('flowmatic').version)"
> # 2.4.1
> ```
The verification step converts a silent failure into an immediate, self-diagnosing one.
## The usage example
**Bad** - constructed:
> ## API
>
> - `createFlow(opts)`
> - `run(flow, input)`
> - `cancel(handle)`
Signatures without a scenario. The reader cannot tell what a flow is, what `opts` accepts, or what running one produces.
**Better** - constructed:
> ## Usage
>
> Retry a flaky HTTP call three times with exponential backoff:
>
> ```js
> import { retry } from "flowmatic";
>
> const body = await retry(() => fetch("https://api.example.com/health"), {
> attempts: 3,
> backoff: "exponential",
> });
>
> console.log(body.status);
> // 200
> ```
>
> This example is in [`examples/retry.js`](./examples/retry.js) and runs with `node examples/retry.js`.
One scenario, real code, the output shown, and the snippet exists as a file so a reader who clones the repository can run it unmodified.
references/published-findings.md›
# Published findings
Every figure this skill quotes, with its source and its strength, plus the folklore numbers to refuse. Read this before repeating a number to a user, and cite the study rather than the skill.
## Strong sources
**Prana, Treude, Thung, Atapattu, Lo - _Categorizing the Content of GitHub README Files_, Empirical Software Engineering 2019 (arXiv 1802.06997).** 393 randomly sampled repositories, 4,226 manually annotated sections, inter-rater kappa 0.858.
Presence of each content category, per file:
| Category | Present in | Reading |
| ------------------------------------------------ | ---------- | ---------------------- |
| What (introduction, background) | 97.0% | table stakes |
| How (install, usage, config, requirements) | 88.5% | table stakes |
| References (links out, API docs, support) | 60.8% | common |
| Who (team, contact, licence, credits) | 52.9% | common |
| Contribution | 27.8% | scarce |
| **Why (advantages, comparison to alternatives)** | **25.7%** | **the differentiator** |
| **When (status, versions, roadmap)** | **21.4%** | **the differentiator** |
| Other (incl. tables of contents) | 6.9% | - |
Size benchmark from the same sample: **median 7 sections**, with half of all files between **5 and 12**. Files under 2 KB were excluded as effectively empty.
Sample composition:
- end-user applications: 42%
- libraries: 27.9%
- learning resources: 17.4%
- frameworks: 7.3%
- UI: 5.4%
Association rules at file level:
- a file containing Who also contains What, with 0.98 confidence
- What implies How, with 0.89 confidence
Categories cluster, so a missing Why is rarely an isolated omission; it signals the README was written as a manual rather than as an evaluation aid.
**Trockman, Zhou, Kästner, Vasilescu - _Adding Sparkle to Social Coding: An Empirical Study of Repository Badges in the npm Ecosystem_, ICSE 2018 (DOI 10.1145/3180155.3180209).** 294,941 npm packages. The strongest evidence base on any single README element. The ACM DOI page itself still 403s to automated fetch, but the 46% badge-adoption figure below is independently re-confirmed via alternate access points (ResearchGate's hosted PDF, the ICSE companion PDF on src.acm.org, and the paper's own supplementary-materials repo, CMUSTRUDEL/npm-badges).
- 46% of packages carry at least one badge.
- Of those, 66% adopted multiple kinds.
- Of those, 82% did so within 24 hours - badges get added in a batch.
- 88 distinct badge types across six classes. The most common single badge (CI build status) appeared on 31.0% of packages.
- Survey of 32 maintainers and 57 contributors: 88% of maintainers treated badge presence as a quality indicator against only 53% of contributors, and 61% of contributors said badges do not influence their decision to contribute at all.
- Signalling theory distinction:
- **assessment signals** - backed by a third-party check and cannot pass unless the underlying fact holds (CI status, coverage, dependency freshness)
- **conventional signals** - merely state an intent ("PRs welcome") and are reliable evidence of nothing
- Popularity: "The adoption of a badge does not change popularity. However, popular projects are more likely to have badges." Among already-popular packages, excessive badge use correlates with _decreased_ popularity.
**GitHub 2017 Open Source Survey** (open dataset, Zenodo record 806811).
- Incomplete or outdated documentation is observed by 93% of respondents, yet 60% of contributors rarely or never contribute to documentation.
- 64% say an open source licence is very important in deciding whether to _use_ a project.
- 67% say it is very important in deciding whether to _contribute_.
The survey itself is robust. It is cross-sectional, so it measures perception at one point in time; it does not prove that adding a file raises adoption.
## Named methods worth citing
**Cognitive funneling** - named by Kira (hackergrrl) in _Art of README_ (CC-BY). Order sections by how quickly each lets a reader bail: name, one-liner, runnable usage, API, installation, licence - with a non-permissive licence moved up, because it disqualifies fastest.
- Stated posture, ego-checking: "Your job is to let them evaluate what your creation does as objectively as possible - not to maximize your downloads or userbase."
- Brevity rule: "The ideal README is as short as it can be without being any shorter."
Counterpoint worth surfacing to a user: makeareadme.com (Danny Guo) argues "too long is better than too short" and recommends moving overflow to another document rather than deleting it. Both agree overflow leaves the README; they disagree on the risk of cutting. The Good Docs Project frames the same rule as keeping "the minimum needed to start using the project" in the README.
**Readme Driven Development** - Tom Preston-Werner, 2010: "Write your Readme first. First. As in, before you write any code or tests or behaviors or stories or ANYTHING." And: "A perfect implementation of the wrong specification is worthless." Useful when the user is starting a project rather than fixing one.
**Ken Williams (Perl)**, on the completeness bar: "Your documentation is complete when someone can use your module without ever having to look at its code… the documentation, not the code, defines what a module does."
**Diátaxis** (Daniele Procida) classifies documentation into tutorial, how-to, reference and explanation. A README is none of them; it is a landing page and router that points at all four. Diátaxis therefore governs the docs site, not the README's internal order.
## Enterprise evaluation signals
- **Div Manickam**, on the buyer/user split: "Buyer: Needs to see ROI, security compliance, and long-term stability. User: Needs to see low latency, ease of implementation, and a strong community… Trust is earned in the code, not the copy."
- **Adam Jacob** (Chef, System Initiative), on the anxiety behind every enterprise trust signal: "Do I trust the supply chain? How do I know? Who do I call if there's a problem? What if there's a security vulnerability and the guy who does the patches is on vacation?… that tends to swing you right back to the proprietary one." (Changelog podcast #460.)
- **Mitchell Hashimoto**, on enterprise technical decision-makers: "90% of TDMs are motivated primarily by NOT GETTING FIRED… they follow secular trends supported by analysts and broad public sentiment." Reported secondhand via Simon Willison, 12 May 2026; attribute it that way.
- Foundation maturity is a real differentiator:
- a graduated project in a major foundation has undergone a security audit and has a documented vulnerability disclosure process
- a sandbox-tier project has not
- A recommended enterprise checklist, drawing on practitioners at CNCF and Buoyant:
- maintainer depth and employer diversity
- release cadence over the last twelve months
- time to fix important bugs and security issues
- governance clarity and roadmap ownership
- The OpenSSF Concise Guide for Evaluating Open Source Software, Microsoft's Code-with-Engineering Playbook, and several published dependency-evaluation checklists independently weight maintenance activity, licence clarity and security posture **above presentation quality**.
## Weak or vendor-influenced sources
- Attribution and "adoption funnel" framings mostly come from vendors selling the measurement product. The framing is useful; the implied causality is marketing.
- Demo-GIF and visual-content advice (short, dark-themed, legible, placed after the tagline) is practitioner consensus, not a measured result. Say so when recommending it.
- Growth-blog case studies bundle README work with a launch spike, so the README's isolated effect cannot be separated from the traffic event.
## Folklore - never cite
- "Repos with detailed READMEs get 50% more contributions, per GitHub's own research." The attribution to GitHub is invented.
- "A star-history chart increases star conversion by ~15%." Self-reported on a growth blog with no methodology.
- "62% of top-100 repos include GIF or video demos." Traces to unverifiable vendor blogs and is correlational at best.
If a user brings one of these, name it as unsourced rather than building the plan on it.
references/readme-skeletons.md›
# README skeletons by project type
Pick the skeleton that matches what the reader is deciding, not what the code happens to be. A library and a CLI can share a language and still need opposite orderings, because one reader is deciding "does this fit my codebase" and the other "does this replace a tool I already run".
Every skeleton below is a starting order, not a template to fill blindly. Drop sections the project does not need; the median README has seven sections and half sit between five and twelve.
## Library or SDK
The reader is evaluating whether to add a dependency. They care about fit and cost of reversal before they care about features.
1. Name and one-line description
2. Badge row (≤4)
3. Two-to-four sentence description: the problem, the approach, the shape of the API
4. Why this over the alternatives - concrete axes only
5. Usage: the smallest complete example, with its output
6. Install, including version/runtime requirements
7. Core API: the handful of entry points, not the full surface
8. Status and stability guarantees (semver policy, breaking-change history)
9. Links out: full documentation, more examples, support
10. Licence, maintainers, contributing pointer
Put usage above install: a reader who dislikes the API shape does not care how to install it, and one who likes it will scroll.
## CLI tool
The reader is comparing against a tool already on their machine. Show the invocation and the output immediately.
1. Name and one-line description
2. A terminal transcript: one real command and its real output
3. Why this over the incumbent tool
4. Install, per platform, with the package-manager one-liners first
5. Common invocations - three or four, each with a comment saying what it is for
6. Configuration: only the options most users touch; link the rest
7. Status, versioning, upgrade notes
8. Licence, maintainers, contributing pointer
A recorded terminal session is fine as an addition, never as the only place the commands appear - a reader on a registry page or in a terminal sees nothing.
## Application, service, or self-hosted product
The reader is deciding whether to run infrastructure. Operational cost dominates.
1. Name, one-line description, screenshot with alt text
2. What it does and who it is for
3. Why this over the hosted or incumbent option
4. Try it: hosted demo, one-command container run, or sandbox
5. Requirements: runtime, memory, storage, external services
6. Install and first-run configuration
7. Architecture in a short paragraph, or one diagram plus a text summary
8. Security and data handling posture
9. Status, release cadence, upgrade and backup notes
10. Support channels, licence, contributing pointer
## Framework or platform
The reader is deciding whether to build on top of you, which is the least reversible choice of all.
1. Name and one-line description
2. The mental model in one paragraph: the two or three concepts everything else derives from
3. Why this over the alternatives, including what it deliberately does not do
4. A complete small application, end to end
5. Install and scaffold command
6. Ecosystem and extension points
7. Stability and long-term-support commitments - this reader will ask about the five-year horizon
8. Documentation, community, governance, licence
## Template, starter, or learning resource
The reader is deciding whether to copy it.
1. Name and one-line description
2. What you will have after using it, stated as an outcome
3. Prerequisites and assumed knowledge
4. Use it: the clone/scaffold command and the first thing to run
5. What is inside: the directory map, briefly
6. What to change first
7. Currency - which versions this tracks and when it was last verified, because a stale starter is worse than none
8. Licence and attribution terms
## Minimal skeleton
For a small, single-purpose project, four sections are a complete README. Padding it does not make it look more serious.
1. Name and one-liner
2. Usage example with output
3. Install
4. Licence
## Sections that usually belong elsewhere
Move these out and link to them; each has a conventional home that tooling already understands.
| Content | Where it belongs |
| ------------------------------------------------ | ------------------------------------------------- |
| Full contribution process, dev environment setup | `CONTRIBUTING.md` |
| Release history | `CHANGELOG.md` |
| Behaviour expectations | `CODE_OF_CONDUCT.md` |
| Vulnerability reporting | `SECURITY.md` |
| Full API reference | documentation site or generated reference |
| Step-by-step teaching material | tutorial in the docs |
| Hand-written table of contents | nothing - hosts generate an outline from headings |
Leave a one-line pointer in the README for each. The point is not to hide the content; it is to keep the README at the length where a reader still reads it.
references/tooling-and-measurement.md›
# Tooling and measurement
An optional integration note. The skill's instructions are written to be tool-agnostic; this file names the specific tools that exist so you can suggest one when the user's environment allows it. Verify a tool is still alive before recommending it - several in this space have been sunset.
## Structural README scorers
| Tool | What it measures | Scale |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------- |
| ScoreMe / `readme-score` (Clay Allsopp) | structural complexity of README text | 0-100 |
| `readme-inspector` (wraps the readme-score API) | existence and quality of a README, usable in CI | 0-100 |
| trymarkdownviewer README Health Score | heading hierarchy 20%, GFM compliance 30%, image alt text 15%, link integrity 25%, task-list completion 10% | 0-100, A+ to F |
| readmecodegen README Score Checker | structural proxies with contextual weighting | 0-100 |
ScoreMe's own description is the honest one: it measures "complexity, which is generally correlated with quality", and it explicitly disclaims judging whether one README is better than another. Treat "complexity correlates with quality" as the author's unvalidated assumption.
The code host's own **community-standards view** is a binary added/not-added checklist over the recognized health files (README, code of conduct, contributing, licence, security policy, issue and PR templates, support, funding, citation, governance). It is a hygiene baseline, not a score.
## Security and package-health scorers
Relevant only when the audience is an enterprise evaluator.
- **OpenSSF Scorecard** - automated security checks (security policy present, packaging, CI tests, code review, best-practices badge), each with a documented risk level. Enterprises do use it in dependency acceptance criteria.
- **OpenSSF Best Practices Badge** (formerly CII) - passing, silver, gold tiers. Unlike Scorecard it accepts claims with justifications from maintainers, trading manual effort for fewer false negatives. Gold requires multiple developers on the project.
- **SLSA** - supply-chain provenance levels, designed for a reader judging organizational risk.
- **Libraries.io SourceRank** - weights how many other projects depend on a package plus documentation and SemVer presence; explicitly positioned as an alternative to star counts. A 2.0 redesign may not be live; verify first.
- **Snyk Advisor** - rated packages across popularity, maintenance, security and community. Being sunset: the standalone site folded into Snyk's security database and went offline in January 2026. Do not recommend it.
## Prose and Markdown linters
- **Vale** - syntax-aware prose linter that understands Markdown, so it excludes code blocks from prose rules. Bundles Microsoft and Google style guides and can enforce a readability score.
- **markdownlint** - structure and formatting.
- Companions: `alex` (inconsiderate wording), `write-good`, `proselint`, `textlint` - heuristic and largely non-configurable.
The common practitioner pattern is Vale plus markdownlint in CI as a merge gate, which stops the README regressing after the rewrite.
**LintMe** (Mynampaty et al., CHI 2026, DOI 10.1145/3772318.3791597) combines programmatic checks with LLM-based content evaluation such as jargon detection. Its own finding is the clearest academic statement of the ceiling: "what constitutes a good README varies across audiences and contexts", and existing linters "concentrate on form rather than substance".
## Terminal demo recording
- **asciinema** records a terminal session as a lightweight text `.cast` file, convertible to GIF with `agg`. Small, and stays crisp at any zoom.
- **VHS** (Charm) renders a GIF, MP4 or WebM from a `.tape` script specifying window size, theme, typing speed and pauses. The advantage over a hand-recorded capture is that the tape file is diffable and re-renderable, so the demo can be regenerated when the CLI's real output changes rather than silently going stale.
Real costs, independent of the conversion question: a GIF can dominate the page weight, and animated content has no alt text, so it is invisible to screen readers and to reading the raw file. Never let a demo carry information that appears nowhere in text.
## Measurement surfaces
- **Code-host traffic insights** - views, unique visitors, clones, referring sites. First-party and needs no integration, but retention is short (daily data is a rolling two-week window on GitHub), so snapshot it rather than relying on it retroactively.
- **Scarf** - cookie-free attribution that works on surfaces the code host cannot see: a gateway redirect that attributes downloads by company via reverse IP lookup, and a pixel embedded in the README or docs.
- It is the only practical way to attribute a registry-page or locally-rendered README view.
- Scarf sells this product and frames documentation views as a funnel step; weight that framing accordingly.
- It states it respects Do Not Track and purges personal data after metadata lookup - confirm the current privacy posture against your own policy before embedding a pixel in a public README.
- **Star-history trackers** - useful for a launch narrative only. Stars are cumulative and monotonic, so they cannot show a regression.
- **UTM-tagged outbound links** from the README to the docs site give a clean click-through number without any third-party pixel.
Funnel frameworks that place a README as a step: AAARRRP (Phil Leggetter, 2016, adapted from Dave McClure's pirate metrics) and the Orbit Model (Josh Dzielak and Patrick Woods), which replaces funnel stages with engagement-depth orbits precisely because community behaviour is not linear. Practitioners including Ben Greenberg have argued publicly against measuring developer relations with a strict sales funnel at all.
## The validity ceiling
Every tool above measures structural completeness, hygiene, or traffic. None measures whether a reader was persuaded to try the project. A high score on any of them is compatible with a README nobody understands.
Use a scorer to catch mechanical regressions, and use the cold-reader test in `audit_scorecard.md` for everything that actually decides adoption.
scripts/readme-audit.sh›
#!/usr/bin/env bash
# Emit mechanical facts about a repository README. Judgement stays with the caller.
# Usage: readme-audit.sh [path-to-readme-or-repo-root]
# Requires: bash 3.2+ (macOS default) or bash 4/5 (Linux), plus grep, sed, awk,
# wc, sort, uniq, tr, head, cut, dirname.
# Portable across macOS (BSD userland) and Linux (GNU coreutils): uses POSIX
# regex classes and no GNU-only flags.
set -uo pipefail
target="${1:-.}"
if [ -d "$target" ]; then
root="$target"
file=""
for candidate in "$root/.github/README.md" "$root/README.md" "$root/docs/README.md"; do
[ -f "$candidate" ] || continue
if [ -z "$file" ]; then file="$candidate"; else echo "SHADOWED: $candidate is never rendered while $file exists"; fi
done
if [ -z "$file" ]; then echo "NO README FOUND under $root (.github/, root, docs/)"; exit 1; fi
else
file="$target"
root="$(dirname "$file")"
[ -f "$file" ] || { echo "NOT A FILE: $file"; exit 1; }
fi
echo "FILE: $file"
bytes=$(wc -c < "$file" | tr -d ' ')
lines=$(wc -l < "$file" | tr -d ' ')
words=$(wc -w < "$file" | tr -d ' ')
echo "SIZE: ${bytes} bytes / ${lines} lines / ${words} words"
[ "$bytes" -gt 512000 ] && echo "WARNING: over 500 KiB, GitHub truncates the rendered view"
[ "$bytes" -lt 2048 ] && echo "WARNING: under 2 KiB — the size at which research samples treat a README as effectively empty"
# Strip fenced code blocks so headings inside examples are not counted as sections.
prose=$(awk '/^[[:space:]]*(```|~~~)/{f=!f; next} !f' "$file")
echo
echo "HEADINGS:"
printf '%s\n' "$prose" | grep -nE '^#{1,6} ' | sed 's/^/ /' || echo " (none)"
section_count=$(printf '%s\n' "$prose" | grep -cE '^#{2,6} ')
echo "SECTION COUNT (h2-h6): $section_count [reference sample: median 7, middle 50% between 5 and 12]"
echo
first_fence=$(grep -nE '^[[:space:]]*(```|~~~)' "$file" | head -1 | cut -d: -f1)
if [ -n "${first_fence:-}" ]; then
pre_words=$(head -n "$((first_fence - 1))" "$file" | wc -w | tr -d ' ')
echo "FIRST CODE BLOCK: line $first_fence, after $pre_words words of prose"
else
echo "FIRST CODE BLOCK: none — the reader never gets a copyable command"
fi
echo
badges=$(head -40 "$file" | grep -oE '\[!\[[^]]*\]\([^)]*\)\]\([^)]*\)|!\[[^]]*\]\([^)]*(shields\.io|badge|badgen|codecov|coveralls|circleci|travis-ci|appveyor)[^)]*\)' | wc -l | tr -d ' ')
echo "BADGES IN FIRST 40 LINES: $badges"
noalt=$(grep -cE '!\[[[:space:]]*\]\(' "$file")
echo "IMAGES WITH EMPTY ALT TEXT: $noalt"
# POSIX ERE has no \b word-boundary token (a GNU-only extension), so the tag
# match instead captures one trailing non-word character (or end of line) to
# rule out a real word merely starting with a tag name (e.g. "<divider>" must
# not count as a "<div" hit). That trailing character is then stripped before
# counting, so grouping by tag name for "sort | uniq -c" is unaffected.
html_tags=$(grep -oE '<(picture|source|details|summary|img|div|table|br|h[1-6])([^[:alnum:]_]|$)' "$file" \
| sed -E 's/[^[:alnum:]_]$//' \
| sort | uniq -c | tr '\n' ' ')
echo "RAW HTML TAGS: ${html_tags:-none} [registries and terminal readers may strip these]"
alerts=$(grep -cE '^>[[:space:]]*\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]' "$file")
echo "GITHUB ALERTS: $alerts [GitHub advises one or two per document]"
echo
echo "BROKEN RELATIVE LINKS:"
broken=0
while IFS= read -r link; do
case "$link" in http*|\#*|mailto:*|"") continue ;; esac
path="${link%%#*}"
[ -z "$path" ] && continue
case "$path" in /*) resolved="$root$path" ;; *) resolved="$root/$path" ;; esac
if [ ! -e "$resolved" ]; then echo " MISSING: $link"; broken=$((broken + 1)); fi
done < <(grep -oE '\]\([^)]+\)' "$file" | sed -E 's/^\]\(//; s/\)$//' | sed -E 's/[[:space:]]+".*"$//')
[ "$broken" -eq 0 ] && echo " (none)"
echo
echo "CONTENT CATEGORIES PRESENT (heading heuristic):"
check() {
if printf '%s\n' "$prose" | grep -qiE "^#{1,6} .*($2)"; then echo " $1: yes"; else echo " $1: MISSING"; fi
}
check "What (intro/overview)" "intro|about|overview|what is|description|synopsis"
check "Why (differentiation)" "why|motivation|compar|alternativ|advantage|when to use|trade-?off"
check "How (install/usage)" "install|usage|getting started|quick ?start|setup|configur|requirement|example|run |build|api|cli|command"
check "When (status/roadmap)" "status|roadmap|version|stability|maturity|release|caveat|limitation|known issue"
check "Who (licence/maintainers)" "licen[cs]e|maintainer|author|credit|acknowledg|team|contact|code of conduct|sponsor"
check "References (docs/support)" "document|docs|support|faq|resource|related|see also|link|learn more"
check "Contribution" "contribut|development setup|hacking|dev environment"
echo " [in the reference sample: What 97%, How 88.5%, References 61%, Who 53%, Contribution 28%, Why 26%, When 21%]"
echo
placeholders=$(grep -niE 'TODO|FIXME|coming soon|lorem ipsum|<your |xxx+|placeholder|\[insert ' "$file" | head -10)
if [ -n "$placeholders" ]; then echo "PLACEHOLDERS LEFT IN FILE:"; printf '%s\n' "$placeholders" | sed 's/^/ /'; else echo "PLACEHOLDERS: none"; fi
echo
toc=$(printf '%s\n' "$prose" | grep -inE '^#{1,6} .*(table of contents|contents)$' | head -1)
[ -n "$toc" ] && echo "HAND-WRITTEN TOC at $toc — GitHub already generates an outline from headings; a manual one goes stale"
exit 0
SKILL.md›
---
name: readme-optimization
description: Audits and rewrites a repository README so a developer who has never seen the project can tell what it is, why it beats the alternative, and run the first command inside a minute - every claim and the documented install verified against the source, the page ordered into a bail-fast funnel, badges that earn nothing pruned. Use whenever someone says "review my README", "my readme is bad", "write a README for this repo", "nobody understands what my project does", "repo first impression", "readme structure", "too many badges", or is preparing an open-source launch - even if they only call it the repo landing page. Not a profile README - use samber/developer-relations-skills@github-profile-optimization.
license: MIT
metadata:
author: Samuel Berthe
version: "1.0.2"
---
# README Optimization
You are working on the single page that decides whether a developer tries a project or closes the tab. Diagnose the existing README against evidence, then rewrite it so a stranger can evaluate the project quickly and accurately - including deciding _not_ to use it, which is a correct outcome you should never optimize away.
A README is not a documentation type. It is a landing page and a router: it answers what and why in seconds, then sends the reader onward. Judge it on whether it converts a visitor into a trial, not on documentation completeness.
Put the rewrite budget where the scarcity is. Across 393 sampled GitHub repositories (Prana et al. 2019, cited in [./references/published-findings.md](./references/published-findings.md); the sample is late-2010s, read it as a baseline, not a census):
- What the project is: 97.0% - table stakes.
- How to use it: 88.5% - table stakes.
- Why to pick it over the alternatives: 25.7% - scarce.
- What state the project is in: 21.4% - scarce.
Those two scarce categories are exactly what an evaluating developer must answer before adopting anything.
Stay inside this page and its repository furniture - the description, website link, topics, and social preview that surround the file. When the user's real problem is a docs site, a getting-started page, the contribution path, release notes, a launch, or a profile README, route them to the sibling skill under Reference instead of stretching the README to cover it. GitHub's platform surfaces around the page - Discussions, release notifications, star policy - belong to `samber/developer-platform-skills@github-engagement-playbook`.
## Folklore statistics to refuse
Never repeat these folklore statistics in your own reasoning or to the user - all three circulate widely on invented attributions:
- "repos with detailed READMEs get 50% more contributions"
- "a star-history chart lifts star conversion ~15%"
- "62% of top repos have GIF demos"
When a user cites one, say it is unsourced rather than building on it. Every figure this skill does quote is cited in [./references/published-findings.md](./references/published-findings.md); read it before repeating a statistic to a user.
Promise a better-evaluated project, never a percentage lift.
## Invocation examples and output shape
Typical requests:
- "audit the README of this repo"
- "our GitHub gets traffic but no installs"
- "rewrite the top of our README before launch"
- "make our README readable by someone evaluating us for their company"
Every run produces a scorecard first, in this shape, before any prose is written:
```
README audit - acme/flowmatic (audience: solo developer)
Band A: A1 pass · A2 FAIL (install needs Node >=20, undocumented) · A3 FAIL · A4 pass · A5 pass
Verdict: does not pass - A2 and A3 blocking; B1 returns the most per hour spent
```
The rewrite follows only after the user agrees with that diagnosis. The full report format, including the claim check, Band B, and the fix order, is in [./references/audit-scorecard.md](./references/audit-scorecard.md).
## Interview
Ask one question at a time, multiple-choice where you can, and skip anything you can determine yourself by reading the repository. Questions 1-4 gate the rewrite - do not draft prose before they are answered.
**Memory: Store a few info about the current task or project context. When memory lives in a file, use `devrel-context.md`; if a different memory system is in use, rely on that instead. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.**
1. Which repository, and can I read it and run commands in it?
2. What is the project: library or SDK, CLI tool, application or service, framework or platform, or template and learning resource?
3. Who lands on this page: developers in one language ecosystem, polyglot developers, platform or ops engineers, or non-developer evaluators such as security and procurement?
4. How does adoption happen - an individual developer installs it and decides alone, or a company adopts it and someone else approves the licence, the security posture, and the support story? Both is a valid answer, and it changes the middle of the page.
5. What outcome do you want more of: installs, contributors, stars, hiring signal, enterprise conversations, or fewer repetitive support questions?
6. What is the honest project status: experimental, actively maintained, stable and feature-frozen, or seeking maintainers?
7. Which alternatives do readers arrive already knowing? What do those do better than you?
8. What must appear for legal or policy reasons - licence terms, trademark notice, export or compliance statements, employer disclosure?
9. Is there existing brand material - a logo, a tagline, a positioning sentence used on a website - that the README should match?
10. Is the README also published elsewhere: a package registry page, a mirror, a docs-site landing page? Each render target has different rules.
11. Is there a date this has to be done by - a launch, a conference, a funding conversation - or is the page just overdue?
12. Do you want a one-off win before that date, or an asset that keeps paying: a positioning sentence and a page shape you reuse for the next two years?
13. What is your ceiling - an afternoon, a week of someone's time, permission to ask customers for a logo, appetite for a governance or foundation commitment you cannot easily undo?
Answers 11-13 re-rank every ordering below; say which answer moved which fix when presenting the plan.
- **Hard date (Q11)** - promotes the fixes that land in an hour, drops the funnel restructure from this pass.
- **Compounding mandate (Q12)** - promotes the differentiation paragraph and the restructure, whose one-liner propagates into the registry page, the launch post, and every link unfurl.
- **Low ceiling (Q13)** - deletes the terminal demo and the enterprise signals outright, rather than parking them at the bottom of a list.
If the user cannot answer 7, treat that as a finding rather than a blocker. A maintainer who cannot name their alternatives usually has a README that cannot differentiate either, and that is the most valuable thing you will fix.
## Step 1 - Declare the audience, then check the README is the bottleneck
Answer 4 decides the whole audit. The enterprise evaluator and the solo developer want structurally different content, and optimizing for one degrades the other: a hobbyist bounces off a wall of compliance badges, and a procurement reader distrusts a page with no security or governance signal. Write the declared audience at the top of your scorecard so every later judgement is checkable against it.
Then confirm the README is what is broken. If the code host exposes traffic data, take unique visitors and clones for the last two weeks.
- Decent traffic with a clone-to-visitor ratio of only a few percent: this is the case this skill is for - people arrive and leave unconvinced.
- Few visitors in the first place: a distribution problem, not a prose problem - route the user to launch or distribution work instead of rewriting a page almost nobody reads.
That "few percent" boundary is a working heuristic, not a benchmark; on a borderline number, look at referrers rather than ruling.
## Step 2 - Gather evidence
Never audit from memory of what good READMEs look like.
1. Read the README in full and note where you personally got confused. Your first-read confusion is the closest thing you have to a cold reader.
2. Run the mechanical audit: `scripts/readme-audit.sh <repo-root>`. It reports:
- shadowed copies
- truncation risk
- the heading tree
- section count against the median of 7
- words before the first copyable command
- badge count
- missing alt text
- registry-hostile raw HTML
- broken relative links
- placeholder text
- missing content categories
3. Read the repository around the README: manifests for the real runtime requirements, the licence file, recent commit dates, open-issue volume, and whether the examples it references exist on disk.
4. If your environment can browse the web, open the project's package-registry page and compare it to the code-host render. Relative links and raw HTML frequently break there, and that page is often the higher-traffic one. A README missing from the published package itself is a packaging fault: hand it to `samber/developer-platform-skills@sdk-package-publishing`.
5. If your environment has persistent memory, reuse any stored positioning statement, audience definition, or competitor list for this project instead of re-deriving it.
Optionally add a structural README scorer and the code host's community-standards checklist as a second opinion, treating both as hygiene baselines - see the validity ceiling in [./references/tooling-and-measurement.md](./references/tooling-and-measurement.md). The script reports facts, not judgements: a section count of 25 is a question to answer, not a verdict.
## Step 3 - Score the current README
Work through [./references/audit-scorecard.md](./references/audit-scorecard.md) and produce the scorecard in the shape above.
- Band A: five blocking checks - identity, the install actually running, every claim verifiable, honest status, reachable licence.
- Band B: eight scored checks, worth two points each.
Attach evidence to every check - a line number, a quoted sentence, or the terminal output of a command you ran. Get the user's agreement on the score before rewriting anything: a maintainer who rejects the diagnosis rejects the treatment, and they are sometimes right, since a constraint invisible from the repository can justify a check you scored zero.
### Order the fixes
Order the fix list by what each fix returns per hour spent, not by how easy it is to write and not by how much damage it undoes - those three orderings disagree, so state all of them and lead with the third:
- effort, least first: `status line == badge row > claim check > install path > differentiation paragraph > funnel restructure`
- value, most first: `install path > differentiation paragraph > claim check > status line > funnel restructure > badge row`
- efficiency, do first: `status line > install path > claim check > differentiation paragraph > badge row > funnel restructure`
The status line and the badge row tie on effort: each is one edit to one block, written from what the maintainer already knows, verified against nothing - no command run, no source read. They separate on value, since a status line answers a question only 21.4% of READMEs answer and a badge row answers one 61% of contributors ignore.
Default to the top three for a first pass; move down once the blocking checks are green, or when the cold-reader test fails on a question none of the three touches.
The funnel restructure loses every round - a week against fixes that land in an hour - so this order under-invests in the one change that makes the page work. Promote it when the cold reader answers wrong because they never scrolled far enough, or when a launch is the reason for the audit, and say you are promoting it against the ratio.
The ordering is a default, not a law, and it shifts with who executes it. Re-rank it against what you already know:
- A maintainer who can name their alternatives in one sentence gets the differentiation paragraph nearly free, which promotes it above the install path.
- A project with no install command - a spec, a dataset, a template - deletes that row rather than scoring it zero forever.
Delete every fix answer 13's ceiling rules out instead of listing it last.
## Step 4 - Verify every claim against the source
A README is a set of claims about a codebase, and every claim is checkable. Agents and maintainers alike write from memory of how an API usually looks; a reader cannot tell a verified line from an invented one, and you can, because you have the repository.
List every claim:
- command
- flag
- default value
- environment variable
- config key
- endpoint
- exported symbol
- file path
- version requirement
- behavioural assertion hidden in a verb, e.g. "automatically reconnects", "retries three times", "case-insensitive"
Verify each against its own source of truth - the argument parser, the definition site, the route table, the changelog - by reading it, not recalling it. A flag documented in the README but absent from the parser is a hallucination, not a typo.
Then run the install path itself, because it catches the most real damage:
1. Start from a clean state - a container, a fresh virtual environment, a temporary directory, whatever your environment supports. If you cannot execute commands, say so plainly and ask the user to run the sequence and paste the output; never mark this check passed on inspection.
2. Execute the documented install command exactly as written, then the first usage example exactly as written.
3. Record every gap: an undocumented runtime version, a system package assumed present, a required environment variable, an output that differs from the README.
4. Fold each gap into the README as an explicit prerequisite or a verification step, then run the sequence again from clean.
Repeat until the documented path runs end to end with no undocumented step. Any performance number, compatibility matrix, scale limit, or "production ready" claim needs a source inside the repository - a benchmark script, a CI matrix, a changelog entry - or it comes out. When you cannot verify something, downgrade the claim to what you can verify and say which part is unconfirmed.
## Step 5 - Choose the shape, then rewrite section by section
Pick the skeleton from [./references/readme-skeletons.md](./references/readme-skeletons.md) that matches what the reader is _deciding_, not what the code happens to be.
- A library reader is judging fit with an existing codebase.
- A CLI reader is comparing against a tool already installed.
- A framework reader is making a multi-year bet.
Order sections by how quickly each lets a reader disqualify the project. This is **cognitive funneling**, named by Kira in _Art of README_: widest and most disqualifying information first, narrowing to detail only a committed reader reaches. One consequence: a non-permissive licence belongs near the top, because it disqualifies fastest and hiding it wastes the reader's time.
Before writing, brainstorm the positioning explicitly instead of reaching for the first phrasing. Draft three candidate one-liners on different axes:
- what it does mechanically
- what problem it removes
- what it lets you stop using
Present them with each one's trade-off and your recommendation, and let the user choose. The one-liner propagates into the repository description, the registry page, and every link unfurl.
Draft one section at a time and get agreement before moving on; per-section approval surfaces a disagreement while it is still cheap to fix. For each section:
1. Write the shortest version that answers its question completely.
2. Replace every unfalsifiable claim ("simple", "blazing fast", "developer-friendly") with something a reader could check - a number, a dependency count, a supported-platform list, a named trade-off.
3. Link every term a reader outside the project's immediate ecosystem might not know.
4. State what the project deliberately does not do, and when to use something else. This is the highest-trust sentence in most READMEs and it costs one line.
5. Move anything that grew past a screen into a linked document and leave a one-line pointer behind. Relocate overflow, never delete it.
Keep community health content out of the file - contribution guidelines, code of conduct, security disclosure, support policy. Each belongs in its own recognized file, which the code host surfaces at the moment it matters; inlining them only adds scroll distance before the reader can decide anything. One exception: the licence file must ship inside the repository, so an organization-level default is not enough.
Run the finished prose through your preferred humanizer skill before presenting it. Copy that reads as generated undermines the credibility the rest of the page is building, and developers spot it easily.
See [./references/before-after-examples.md](./references/before-after-examples.md) for worked positive and negative examples of the opening lines, the differentiation section, the status statement, badge rows, install blocks, and usage snippets.
## Step 6 - Calibrate badges to the evidence
Badges are the one README element with a rigorous evidence base: Trockman et al. studied 294,941 npm packages (ICSE 2018). Use the study's distinction rather than taste.
- Keep **assessment signals** - badges backed by a third-party check that cannot pass unless the underlying thing is true: CI status, coverage, published version, dependency freshness.
- Cut **conventional signals** - badges that merely state an intent, such as "PRs welcome", with nothing verifying them. They signal nothing.
- Cap the row. Among already-popular packages, excessive badge use correlates with _decreased_ popularity, and adopting a badge does not raise popularity at all - popular projects are simply likelier to have badges. The direction is sourced; the cap of four is a working default here, not a published figure, so justify each survivor by the reader question it answers rather than arguing about the number.
- Expect the maintainer to over-value them. The study's small companion survey found maintainers rate badges as a quality indicator far more often than contributors do, and most contributors say badges do not influence them at all. Quote the figures from [./references/published-findings.md](./references/published-findings.md) when a maintainer resists cutting the row.
## Step 7 - Fix repository furniture and render mechanics
Three things compete for this step's budget, and they are not close:
- efficiency, do first: `furniture > render mechanics > terminal demo`
- **Furniture** is near-zero effort and buys the only text a reader sees before opening the repository: the description, website link and topics are what search listings carry, and the social preview is what unfurls when someone pastes the link into a chat.
- **Render mechanics** cost about an hour and buy the page working for readers who never see the code host's render - registry pages, terminals, screen readers.
- **Terminal demo** costs a week to produce well and then becomes a standing job, going stale whenever the output changes.
The demo is what this order starves, and it is the highest-value element on the page for a CLI or a visual tool, where the output _is_ the product. Promote it above render mechanics in exactly that case, and generate it from a script rather than hand-recording it, so re-rendering stays cheap enough to survive as a standing job. Delete it for a library with no visible output - a demo of an import statement earns nothing - rather than leaving it to reappear as scope later.
Fix the furniture, then fix how the file itself renders:
1. Give every image alt text, and move any instruction, command, or decision-relevant fact out of screenshots and animated demos into text. Readers meet READMEs in terminals, on registry pages that strip HTML, and through screen readers - an animated demo is invisible to all three.
2. Delete a hand-written table of contents - code hosts generate an outline from headings, and the manual copy goes stale.
3. Check that relative links resolve from the repository root on the default branch, and that the page still reads correctly where raw HTML is stripped.
4. Keep only one rendered README. Where a host renders a `.github/` copy in preference to the root file, the root copy is what registries and mirrors publish, so the two silently diverge.
5. In a monorepo, make the root README a router to the per-package READMEs rather than covering every package inline.
When the demo does earn its place, keep it short, high-contrast and legible at embed scale, and place it right after the tagline. Treat its conversion benefit as practitioner consensus rather than a measured result - no study prices it, which is another reason not to let it outrank the two cheaper rows by default.
## Step 8 - Add enterprise trust signals, only if the audience calls for them
Run this step only when Step 1 declared a company or procurement audience.
An enterprise decision-maker optimizes for defensibility, not best technical fit, so recognizable third-party signals - a foundation tier, an audit, an attestation, a well-known adopter - outperform novel claims. Published evaluation checklists weight maintenance activity, licence clarity and security posture above presentation quality; sources are in [./references/published-findings.md](./references/published-findings.md).
Six signals are available, spanning two orders of magnitude in what they cost:
- effort, least first: `support expectation == release cadence > security policy > named adopters == supply-chain attestation > governance and maintainer depth > foundation affiliation`
- value, most first: `foundation affiliation > named adopters > security policy > governance and maintainer depth > supply-chain attestation > release cadence == support expectation`
- compliance cost:
- foundation affiliation demands trademark or IP assignment and a legal sign-off you cannot walk back
- named adopters need each company's own marketing approval, revocable but only by asking again
- a security policy commits you publicly to a response window you then have to honour
- the remaining three trigger no review and are reversible with one commit
- efficiency, do first: `support expectation == release cadence > security policy > named adopters > governance and maintainer depth > supply-chain attestation > foundation affiliation`
Support expectation and release cadence tie twice over: each is one sentence stating something already true, needing nobody's permission and no work beyond reading the commit log. Named adopters and supply-chain attestation tie on effort at about a week each, but separate on efficiency - the attestation persuades an engineer who was going to say yes anyway, while a recognizable logo persuades the person who signs.
Default to the first three, an afternoon between them, which clear most of what an evaluation checklist scores. Move to named adopters when a deal is in the room and someone has asked "who else runs this".
Foundation affiliation is what this order starves: strongest signal on the page, a quarter or more of work, so it never wins on ratio and a README-driven plan never reaches it. Promote it when the project is being adopted as infrastructure rather than as a dependency, or when a foundation tier is the objection you keep losing to - then hand that decision to the user, because its reversibility cost is not a documentation cost.
Delete every signal answer 13 rules out instead of listing it as future work: no legal appetite means no foundation row, and a solo maintainer writes an honest support expectation rather than an empty governance heading.
## Step 9 - Re-score and test with a cold reader
Re-run the scorecard. The README passes when all five blocking checks pass and the scored checks total at least 14 of 16 - a working default here rather than a published bar, so let the user move it for a stated reason you record in the report.
Then run the cold-reader test defined in the scorecard - five questions, 60 seconds, five correct answers to pass - using a person if the user can find one, otherwise a fresh agent session with no repository context. Each wrong answer maps to a specific check, so a failure tells you exactly what to fix.
If your environment has persistent memory, store the agreed one-liner, audience definition, competitor list, and final score. Sibling work - launch posts, docs landing pages, conference abstracts - should start from that positioning rather than inventing a new one.
## What to track afterwards
Attribution on a README is weak. Record the ship date, compare a full period before against a full period after, and annotate confounders instead of claiming the delta. Re-measure four to six weeks out; shorter windows are noise.
- efficiency, track first: `support load > conversion rate > contributor conversion`
- **Support load** costs nothing to track and moves within weeks: count the "how do I install this" and "what does this do" issues per month and watch them fall.
- **Conversion rate** - clones or downloads divided by unique visitors - takes an hour to assemble from the host's traffic data and is the truest single number available, but says nothing until a full period has passed either side.
- **Contributor conversion** is slowest and most confounded; read it a quarter out.
Drop stars from the tracking plan entirely, even when answer 5 named stars as the goal: they only ever go up, so the metric cannot show a regression and reports success for a change that made the page worse. Offer the conversion rate instead.
If clones rise but contributor count does not, the contribution path is broken, not the README. Measurement surfaces and their caveats: [./references/tooling-and-measurement.md](./references/tooling-and-measurement.md).
## Common failure modes
**Rewriting before diagnosing.** A rewrite that fixes the prose and preserves the broken install has fixed nothing. In review mode, do not rewrite at all unless asked.
**Padding to look serious.** Half of all READMEs sit between 5 and 12 sections, median 7. A four-section README for a single-purpose project is complete; adding architecture and roadmap sections to a 200-line utility makes it look abandoned, not mature.
**Marketing voice.** Superlatives without evidence read as noise to this audience and actively lower trust. Every claim should be checkable or cut.
**Auditing only one render target.** The registry page frequently has more traffic and different rules. A README that only works on one host is broken for a large share of its readers.
**Fabricated status.** Never write "production ready", "battle-tested", or a user count you did not get from the user. An overstated claim is disproved by one glance at the commit history and costs more trust than an honest "early beta".
**Leading with the cheapest fix.** The badge row is the fastest thing on the list and nearly the least valuable. Present the order from Order the fixes, not the order you could finish first.
## Reference
- [./references/audit-scorecard.md](./references/audit-scorecard.md) - Rubric, thresholds, cold-reader test, and report format.
- [./references/published-findings.md](./references/published-findings.md) - Every sourced figure and the folklore list.
- [./references/readme-skeletons.md](./references/readme-skeletons.md) - Section orderings per project type.
- [./references/before-after-examples.md](./references/before-after-examples.md) - Worked positive and negative examples.
- [./references/tooling-and-measurement.md](./references/tooling-and-measurement.md) - Scoring, linting and attribution tools.
- [./scripts/readme-audit.sh](./scripts/readme-audit.sh) - Mechanical facts the scorecard depends on.
- samber/developer-relations-skills@developer-quickstart-guide - Dedicated getting-started page.
- samber/developer-relations-skills@developer-docs-structure-audit - Documentation site structure.
- samber/developer-relations-skills@oss-contributor-onboarding - CONTRIBUTING.md and first-contribution path.
- samber/developer-relations-skills@changelog-writing - Release notes and changelog structure.
- samber/developer-relations-skills@oss-launch - Launch planning and execution.
- samber/developer-relations-skills@oss-distribution-strategy - Which channels point readers at this repository surface.