Smithery is now a part of Arcade.dev! Read more in our announcement here
Writes and refines a repository's README.md in a concise, Nuxt-inspired documentation style: sections chosen from what the repository actually contains, scannable feature bullets, emoji-anchored...
Produce a README that carries a new reader from "what is this" to "it works on my machine" with nothing in the way.
The style is descended from the Nuxt ecosystem: short introduction, feature-oriented presentation, fast path to first success, clear next steps, minimal ceremony. Two things separate it from a generic README. Sections are chosen from evidence in the repository rather than from a fixed template, and every claim traces back to a file you actually read.
These hold on every run, for every repository.
## Features takes no emoji. Neither does ## Background or ## Why?. Every other user-facing H2 takes one.Do not work from the existing README alone. It is a claim about the project, not evidence. Read it first so you know what it asserts, then carry a line forward only after you have verified it against a file.
If it carries generator markers such as <!-- commands -->, <!-- ALL-CONTRIBUTORS-LIST:START -->, or <!-- START doctoc -->, a script owns that block. Leave the markers and everything between them untouched, even when the content breaks a rule here, and tell the user instead.
Read what materially describes how the project works, which usually includes package manifests and lockfiles, workspace configuration, entry points (CLI, application, or public API), source that implements the headline behavior, configuration files and schemas, environment variable definitions, scripts, tests, examples and playgrounds, CI workflows, release configuration, the license file, and any existing contributing or architecture documentation.
Read the scripts block before you document a single command. Inventing npm test for a repository that uses bun test is the most common way this task fails.
The lockfile picks the package manager for every command run inside the repository. bun.lock or bun.lockb means bun, pnpm-lock.yaml means pnpm, yarn.lock means yarn, package-lock.json means npm, and a packageManager field in the manifest overrides all of them. The same logic applies outside JavaScript, where uv.lock means uv, poetry.lock means Poetry, and Gemfile.lock means Bundler. The install line a consumer runs against a published package is not bound by this.
Use version control history only to settle a specific question, such as whether documented behavior is current. Stop once the question is answered.
You are answering: what does this do, who is it for, what is the shortest path to it working, how is it normally used, what can be configured, what are its real constraints, how do contributors work on it, and what is its license.
Read references/section-rules.md now, before choosing an outline. It gives an inclusion test for every optional section and the default ordering.
Resolve ordinary choices yourself from repository evidence and the rules in this skill. Do not ask the user which sections they want.
Read references/style-guide.md before writing prose. It covers opening chrome formats, heading and emoji conventions, tables, code blocks, diagrams, linking, tone, and license wording.
Read assets/readme-template.md only when you are building a README from nothing or substantially restructuring one. It is a skeleton of optional parts, not a form to fill in. Skip it when you are making a targeted revision.
When refining an existing README, preserve what already works. A strong README should receive small, surgical edits, not a rewrite. Chrome follows the inclusion tests, not the incumbent README: strip badges stating unproven facts, banners with no committed asset, and Documentation or Playground bullets with dead targets, and say so in your summary. Keep the chrome the repository earns, normalized to the format in references/style-guide.md.
Before you finish, check each of these against the repository:
./path form.license field when there is no LICENSE file. Never infer a license, and never write MIT because it is common.If you used any GitHub alert, confirm the current syntax, the supported types, and the usage limits against https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax. references/style-guide.md records what that page said when this skill was written, which is a starting point and not a substitute for checking. If you cannot reach the page, use the recorded rules and say plainly that live verification was unavailable. Never claim you verified something you did not.
Review the final diff. The only file that should have changed is the README, plus anything the user explicitly asked for.
The first elements, in this order, with nothing before them:
references/style-guide.md.# Title. Use the exact package name for a publishable package, otherwise a readable product name.references/style-guide.md.references/section-rules.md. Usually that is ## Features.A leading alert can carry the one-sentence description itself when the caveat and the description are the same thought, which is common for private or license-constrained packages.
- 🎯 **Feature name:** One sentence stating the concrete capability or benefit.
One emoji chosen for that specific feature, with no emoji appearing twice in the list, then a bold label of one to four words in sentence case, a colon inside the bold, then one full sentence. The label is a noun or adjective phrase naming the capability, and it may be a link when the feature has a canonical page, such as the technology it wraps or its own docs guide, written **[Label](url):** with the colon inside the bold and outside the link. Link a label only where the target genuinely helps, not on every bullet. The sentence is present tense, leads with an active verb, makes one primary claim, ends with a period, and stays as short as accuracy allows. Aim for the whole bullet to render on one line, which usually means a description of eight to fifteen words, and run longer only when precision demands it. No dangling fragments: "Uses chezmoi in symlink mode with Go templates for per-machine configuration", not "chezmoi in symlink mode, Go templates for per-machine configs".
Lead with the capability and order the list from defining to supporting. Name what the project does that a reader could not assume, with the specific verb rather than the generic one, and write "Supports" only when compatibility itself is the feature. State whether behavior is automatic or opt-in, and do not word configuration-dependent behavior as a guarantee. Round a count that grows with the project down to a stable floor, 100+ rather than 123, so the sentence stays true as the project moves. A count that is itself the fact, such as a default value, or one small enough that the list could name each member, stays exact. Skip "powerful", "modern", "blazing fast", and "easy to use" unless the repository proves the claim, in which case state the proof instead of the adjective.
Aim for about four to fifteen bullets, past fifteen only when the project genuinely has more important features than that, and below four when it genuinely has fewer, since two nameable capabilities still earn the section. Features is a summary, not an inventory, so implementation detail belongs in a later section or nowhere.
Prefer a sensible default over a question. Resolve decisions in this order: repository evidence, then this skill's rules, then general technical writing judgment.
Ask only when a decision materially changes the README and evidence cannot settle it. That means ambiguous project positioning, two genuinely competing primary audiences, unclear or risky licensing claims, sensitive wording, or two materially different user journeys with no clear primary path.
When you do ask, ask one focused question, explain what actually differs between the options, recommend one, and say why in a sentence.
If you cannot ask, pick the safest option and state the assumption in your summary to the user, not in the README.
Change the README. Change other documentation only when the user asked for it.
Do not touch application behavior, architecture, source, dependencies, generated files, snapshots, fixtures, test expectations, or third party content. Do not rewrite unrelated prose elsewhere in the repository because you noticed it could be better.
If writing the README exposes a bug or a contradiction between docs and code, report it to the user. Do not silently fix it in the implementation.
references/section-rules.md.## Features. It never takes one. ## Background and ## Why? never take one either.## Why? and ## Background with overlapping content. Pick the one that does the job.Prerequisites when the only prerequisite is the language runtime the install command already implies.Examples when the repository has no examples, or pointing it at test fixtures that were never meant as examples.Next Steps that only relink earlier sections. It must be a progression toward something new.WARNING and CAUTION mean something specific. Check the definitions.cache/ is not evidence of a caching feature.npm run build without opening the manifest to see whether that script exists.