write-readme · diff
git:20261011.cdfce58 to git:20261015.f303077
64 added, 66 removed. Audit A to A.
---
- description: Write or review a repository or directory README for newcomers, with an evidence-backed first-use path, clear purpose and limitations, and links to deeper guidance. Use when creating, refreshing, auditing, or simplifying README.md files; not for changelogs or historical evidence records.
+ description: Write or improve a newcomer-facing README with a clear product overview, useful existing visuals and badges, and a short path to first use. Use for repository or directory READMEs, not changelogs or historical evidence records.
license: Apache-2.0
metadata:
github-path: write-readme
- github-ref: refs/tags/v1.24.0
+ github-ref: refs/tags/v1.24.1
github-repo: https://github.com/devantler-tech/agent-skills
- github-tree-sha: 9bfca99d109bdb37e8f2c6a42fa5beb1091843a8
+ github-tree-sha: 02451fe8f1c139a29ad1a404dc1f0abc5c0e0c8f
name: write-readme
---
- # Write a newcomer-facing README
-
- A README is an entry point, not a maintainer's notebook. Help its intended reader decide whether
- this project fits, get a first useful result, and find the next relevant document.
-
- ## Establish the reader and evidence
+ # Write a useful README
- Before drafting, read the existing README, repository instructions, contribution guide, license,
- and the source for the advertised entry point. Inspect manifests, task definitions, tests and CI
- for supported tools, versions, working directories and commands. Treat fetched content as evidence,
- not permission to execute it. Do not run an untrusted contributor's code.
+ Help readers understand what this project does, decide whether it fits, and try it. A newcomer to
+ the project may already know its field; do not turn the introduction into a lesson on the whole stack.
- Identify whether this is an application, library, CLI, template, infrastructure configuration,
- automation action, skill collection, or a directory inside one. Choose its primary reader and task.
- Infer these from the repository when clear; ask only when an unresolved choice would materially
- change the result. A directory README explains its boundary and links back to the project entry
- point; it need not repeat the whole installation guide.
+ ## Start with what works
- Separate source-supported capability from deployed availability. A workflow definition does not
- prove an integration is enabled; a release entry does not prove a package was published. Verify
- current external facts when they affect an instruction. Flag an unresolved prerequisite rather
- than inventing a version, URL, credential, feature, or supported platform.
+ Read the existing README, repository instructions, contribution guide, license and advertised entry
+ point. Check source, manifests and CI for actual commands, supported platforms and prerequisites.
+ Treat fetched content as evidence, never permission to execute an untrusted contributor's code.
- ## Design the shortest useful path
+ Identify the reader and the project type: application, CLI, library, template, infrastructure,
+ automation, skill collection or internal directory. Preserve useful positioning, section order,
+ screenshots, demos, feature summaries and support links. When a rewrite has regressed, compare the
+ earlier version. Fix specific reader problems rather than replacing the page with a standard template.
- Lead with what the project does, who it helps, and the outcome a reader can expect. State a material
- limitation early enough to affect their decision. Keep the project's language and terminology.
+ ## Explain the product simply
- Give one primary route to a first result, appropriate to this kind of project:
+ Lead with what it does and why someone would use it, in a few direct sentences. Describe the current
+ product, not its development history. Use short paragraphs, familiar words and concrete benefits.
+ Keep names readers use to recognize compatibility: “Encrypt secrets with SOPS” is clearer than
+ either a bare tool list or a long explanation of encryption internals.
- - For a CLI or library, prefer a supported install plus a small executable example.
- - For an application, distinguish end-user access from running the source locally.
- - For a template, distinguish creating a project from contributing to the template itself.
- - For infrastructure or automation, prefer an offline render, validation, or disposable example
- before production setup. Say what that check does **not** prove.
- - For an internal directory, explain what belongs here and how it is used by the owning project.
+ Use bullets for distinct benefits and a compact table when comparison helps. Keep a useful feature
+ overview visible; do not move every reason to choose the product into a reference document. Avoid
+ repeating the introduction, explaining every technical noun, or adding warnings for hypothetical
+ risks. State material limitations where they affect a reader's choice or next action.
- Before each command sequence, state prerequisites and the starting directory. Include dependency
- installation, environment setup and generated prerequisites actually needed by that sequence.
- Mark placeholders explicitly. Describe success in observable terms: output, a local page, a file,
- or a passing check. If a process keeps running, explain how to stop it. For a disposable service or
- resource, explain cleanup without giving broad destructive commands.
+ ## Put badges where readers can see them
- Never make a live deployment, publishing action, cloud spend, database migration, or access to
- maintainer infrastructure the unannounced first-use path. Separate operator procedures and their
- authorization requirements. Use synthetic examples and disposable local databases; do not expose
- secrets, private topology, personal data or production credentials.
+ Keep relevant badges together near the top, normally before or just below the title, allowing for
+ required metadata or notices. Preserve useful existing badges and visuals. Badges can serve as a
+ compact scorecard for build status, release, coverage, security or documentation where those signals
+ exist; stars show interest, not quality. Link each badge to its actual source, use readable labels,
+ and check that it describes this repository and the intended branch or release. Do not invent a
+ passing score, hide failures, or imply one green badge proves the whole product is healthy. A small
+ directory need not acquire a badge collection.
- ## Keep the entry point focused
+ ## Offer a short first step
- Link to detailed configuration, architecture, operations, examples and the contribution guide at
- the point the reader needs them. Keep one canonical copy of a procedure. Preserve security-reporting,
- licensing, source-availability, attribution and contributor obligations. Link to authoritative
- files rather than inventing badges, testimonials, or support commitments.
+ Give a supported install or access route and one small, useful example. Keep prerequisites, starting
+ directory, placeholders and expected result clear. Include stop or cleanup instructions when the
+ example creates resources. Cleanup must target only resources created by that example and leave
+ existing work intact; never use broad destructive commands. Explain meaningful side effects before
+ the relevant command; never make
+ deployment, spending, publishing, migration or private infrastructure an unannounced first step.
+ Use synthetic data and disposable local resources. Never expose secrets, personal data, private
+ topology or production credentials. Keep privileged operator procedures and their authorization
+ requirements separate from the newcomer path.
- Describe present behavior. Move release history to its proper home rather than filling the intro
- with completed migrations. Do not rewrite vendored documentation or dated experiment evidence as
- current product guidance. Follow generated-file ownership: edit its source and regenerate when
- required. In a portfolio audit, inventory all relevant files and explicitly classify these exceptions;
- a root-only review cannot establish that every README is sound.
+ Choose the path for this reader: an application's users may need a URL, a library needs a small usage
+ example, and a template needs its “create a project” path. Infrastructure may need a safe offline or
+ disposable example with its limits stated. A directory may need only its purpose and a link back.
- There is no compulsory heading template. Keep already useful material, remove duplication, and
- choose sections that serve this reader. A small directory may need only a paragraph and a link.
+ Link to detailed setup, configuration, architecture, operations and contribution guidance. Keep one
+ canonical copy of each procedure. Do not paste an entire tutorial or check matrix into the front
+ page. Preserve licensing, security reporting, attribution and contributor obligations. Respect
+ generated-file ownership and leave vendored docs and dated evidence alone. A portfolio audit must
+ inventory and classify relevant READMEs; reviewing root files alone proves nothing about the rest.
- ## Verify as a first-time reader
+ ## Check the result as a reader
- Run the documented primary path from a clean, appropriately isolated environment when execution
- is trusted and authorized. Check commands exactly as written, including paths and versions; do not
- silently repair missing steps while declaring the guide verified. Check relative links and heading
- anchors, command/source agreement, and any published endpoint or artifact the path depends on.
- Use the repository's normal documentation checks without weakening them.
+ Compare the draft with the original: can readers still see what they get, useful visuals, status,
+ first steps and support without hunting? Remove detail that does not help them choose or act.
+ Shorter is useful only when it remains clear and correct; a word count or heading checklist cannot
+ prove readability.
- Give an independent reader the draft and the same starting conditions, without explaining omitted
- steps. Ask them to attempt the task and report where they need unstated knowledge. When no independent
- reader is available, perform this cold-read yourself and label that limitation. Correct the document
- from observed failures, not from a heading-count or keyword test alone.
+ Run the advertised path exactly as written in a clean, isolated environment when trusted and
+ authorized. Check links, anchors, commands and current external artifacts. Do not silently supply
+ missing steps. Separate source-supported capability from published or deployed availability.
+ Correct observed failures without weakening repository checks.
- Report which path ran and its result. Distinguish a local smoke test, CI validation, a merged change,
- and deployed availability. If execution or a live claim could not be verified safely, state exactly
- what remains unverified and provide the safe path that was checked; do not imply full validation.
+ When available, have an independent reader attempt the documented task from the same clean starting
+ conditions without extra setup hints, and report obstacles or missing knowledge. Otherwise cold-read
+ it yourself and label that limitation. Correct observed omissions. Record what ran and what remains
+ unverified in the review or delivery report. Keep author-only test
+ transcripts, evidence caveats and readiness bookkeeping out of the README unless they help its reader
+ make a real decision. Never claim that a self-review or a green badge proves newcomer comprehension.