agentleFS
asale-aiasale-ai/anything-to-skill/.agents/skills/repolish/SKILL.md

repolish

Skill5 starsChanged 3 months agoApache-2.0View on GitHub

Diagnose and improve what an open-source repository looks like to a first-time visitor. Use when asked to review, score, or improve a README, a repository's documentation, its "first impression", its discoverability, or its open-source hygiene (license, CI, contributing guide, issue templates) — and before rewriting any README by hand. Also use to generate the SVG overview card, the report card, SVG tables, or a VHS terminal recording for a CLI.

  • Pipes a download into a shell
  • Reads credentials
  • Installs packages

2 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 1

    1. asale-ai/seo-geo-skill★ 623% same

    Wrote their own version · 1

    1. brandonhenry/repolish★ 4same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repositoryOne other file it gives its agents.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 4 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Only edit prose directly when a finding names a specific line and the fix is unambiguous, and say which finding you were acting on.

    line 38
  2. Very specific:

    Check first, then install: Every command below calls repolish by name, so start by finding out whether it is already there:

    line 43
  3. Very specific:

    If that prints a version, use repolish as written throughout this document.

    line 50
  4. Very specific:

    If the user would rather have it on PATH permanently, this installs the binary into ~/.local/bin and drops this skill into whichever agents …

    line 72
  5. Very specific:

    Read score: null as "no score", not zero: it means fewer than half the registered checks could run.

    line 147
  6. Distinctive:

    Every SVG is self-contained and deterministic: no external fonts, no scripts, nothing hosted by a third party, and the same commit renders …

    line 220
  7. Distinctive:

    Cite the finding: Every edit you make should be traceable to an id and a file:line that repolish reported.

    line 296
  8. Distinctive:

    If you are wondering whether to suggest wiring an LLM into it: the scoring path is deliberately model-free, and that is not conservatism.

    line 307
  9. Very specific:

    Report the numbers the tool gave you: If it says not scored, say not scored.

    line 330

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

repolish

A command-line tool that scores 22 concrete signals about a repository and, for every point it deducts, names the file and line and says what to write instead.

No model is in the scoring path. The same commit always produces the same score. You may suggest wording; you must never claim a number the tool did not produce.

The rule that matters most

Do not rewrite the README. Your instinct will be to replace it with a well-structured one. That destroys the author's voice, their layout, their examples, and usually their accuracy. Instead:

  1. Measure. repolish — one command. It scores the repository and prints every file it would touch, and it writes nothing.
  2. Show the user that plan, then apply it. repolish --apply — badge, table of contents, issue/PR templates, CONTRIBUTING.md, the CI workflow. It only ever inserts; the diff is new lines and nothing else.
  3. Hand back what needs judgement. A missing quickstart, a vague tagline, a README claim whose command no longer exists — those need the author's knowledge, or a targeted edit you can justify from evidence.
  4. Measure again and report the delta — repolish --stages check --base <ref> does the arithmetic for you and lists only the checks that moved.

Only edit prose directly when a finding names a specific line and the fix is unambiguous, and say which finding you were acting on.

Install

Check first, then install. Every command below calls repolish by name, so start by finding out whether it is already there:

repolish --version

If that prints a version, use repolish as written throughout this document. If it says "command not found", reach for npx — it needs nothing installed and works wherever Node does:

npx -y @asale/repolish

Then read every repolish … below as npx -y @asale/repolish …, for the rest of the session. The -y matters: without it npx stops to ask, and you are not at a terminal to answer.

npx does not install anything onto PATH. It downloads into a cache and runs from there, so repolish still will not exist after you have used it once — and the tool's own output says npx @asale/repolish … back to you for exactly that reason. Never drop the prefix partway through, and never tell the user to run bare repolish unless repolish --version worked above.

That package is a launcher — it downloads the release binary, verifies its .sha256 and execs it, forwarding the exit code, which is what --min-score depends on. The current version is 0.4.0.

If the user would rather have it on PATH permanently, this installs the binary into ~/.local/bin and drops this skill into whichever agents it finds:

curl -fsSL https://raw.githubusercontent.com/asale-ai/repolish/main/install.sh | sh

cargo install repolish works too, as does a release binary from https://github.com/asale-ai/repolish/releases (five targets, each with a .sha256).

Commands

There are no subcommands. repolish is the whole surface; --stages picks which parts of the pipeline run. The default is check,polish,artifacts,ci.

StageWhat it does
checkScore the repository and print the report
polishThe mechanical fixes: badge, table of contents, issue/PR templates, CONTRIBUTING.md
artifacts.repolish/badge.json, the banner, the overview and report cards, and every SVG the README already references
ci.github/workflows/repolish.yml
skillSKILL.md — opt-in, not in the default run
demoRecord the CLI — opt-in, and with --apply it executes the commands. A run that skipped it says so at the end

Run it

repolish                            # everything, and nothing is written
repolish --apply                    # write it
repolish --apply -v                 # also print every new file in full
repolish --stages check             # score only, no network
repolish --stages check --remote    # also read description / topics / homepage from GitHub
repolish --stages check --format json      # machine-readable, schema frozen at version 1
repolish --stages check --min-score 70     # exit 1 below the threshold, for CI
repolish --stages check --base origin/main # also score that ref, report only what moved
repolish --stages check --sarif out.sarif  # SARIF 2.1.0, for GitHub code scanning

--remote reads GITHUB_TOKEN or GH_TOKEN. Without a token it falls back to 60 anonymous requests per hour.

Always run it once without --apply and show the user the plan. The dry run is free, and it is the whole safety story: nothing lands in the author's repository that they have not seen first.

Prefer --format json when you are going to act on the result. The text output is laid out for a human reading a terminal; the JSON is stable and tells you, per check, the score, the evidence (file and line) and the fixes.

Shape of the JSON, abridged:

{
  "score": 82,
  "coverage": 0.86,
  "mode": "remote",
  "categories": [{ "category": "credibility", "score": 90 }],
  "checks": [
    {
      "id": "license",
      "category": "credibility",
      "risk": "critical",
      "outcome": {
        "kind": "scored",
        "score": 0,
        "evidence": [{ "file": ".", "line": null, "note": "no LICENSE file" }],
        "fixes": [{ "severity": "P1", "message": "Add a LICENSE file" }]
      }
    }
  ],
  "coverageLimits": ["repo-topics: requires --remote"]
}

Read score: null as "no score", not zero: it means fewer than half the registered checks could run. Report that honestly rather than picking a number.

An outcome can also be notApplicable, inconclusive or skipped. Those are excluded from the score on purpose. Never present them as passes.

Fix what can be fixed

The polish stage is in the default run, so repolish --apply already does this. To do it without the badge JSON and the CI workflow:

repolish --stages check,polish            # dry run: print the changes it would make
repolish --stages check,polish --apply    # write them

What it will do: the repolish badge (plus the .repolish/badge.json it points at), a table of contents built from the author's own headings, GitHub issue and PR templates, and a CONTRIBUTING.md whose build and test commands come from the detected package manifest.

What it will not do: rewrite a single existing line, invent a build command when there is no manifest, or write a code of conduct. Where it cannot know, it does not write.

--apply refuses to run outside a git repository unless you pass --force, because git checkout is the undo button. Never pass --force on the user's behalf without saying so.

Wording you are allowed to suggest

repolish --suggest                  # needs REPOLISH_LLM_API_KEY

This asks a model for the three pieces no mechanical rule can write: the tagline, the quick start, the usage example. It prints and never writes, not even with --apply.

You usually do not need it — you are a model, and you are already here. It exists for the author running the CLI without you. If you are drafting those sections yourself, hold to the same three rules it does: fill the gap, never rewrite what is there, and never invent a command that is not in the manifest.

The visuals

repolish --stages artifacts --apply                     # redraw everything already referenced
repolish --stages artifacts --apply --artifact overview # just .repolish/overview.svg
repolish --stages artifacts --apply --artifact score    # just .repolish/card.svg
repolish --stages artifacts --apply --theme porcelain   # light palette, for a light README
repolish --stages artifacts --apply --lang zh-CN        # en / zh-CN / ja; follows the README
repolish --stages artifacts --apply --remote --stars    # star history curve (~12 extra API calls)

The overview card goes at the top of the README: languages, file composition, commit activity, licence. The score card goes at the bottom, under a "Polished with repolish" heading. Do not swap them — the top of a README belongs to the project, not to our tool.

To have polish insert them, and render README tables as SVG with the original folded into <details>:

The cards and the SVG tables are on by default, so a plain --apply inserts them. --no-visuals leaves the README's visuals alone — reach for it when the author has a README they clearly art-directed themselves.

repolish --apply                    # cards and SVG tables included
repolish --apply --no-visuals       # leave them alone
repolish --apply --logo assets/hero.svg --logo-width full --align center

Every SVG is self-contained and deterministic: no external fonts, no scripts, nothing hosted by a third party, and the same commit renders a byte-identical file.

Record a CLI

repolish --stages demo                  # list what it would run, run nothing
repolish --stages demo --apply          # run them, and write .repolish/demo.svg
repolish --stages demo --apply --cmd "tool build" --cmd "tool run"
repolish --stages demo --apply --tape   # also write a VHS tape, for a GIF instead

With --apply this executes the commands. That is the point — the output in the recording is real — but it means you must not run it against a repository whose commands you have not looked at. Run it without --apply first and show the user the list. Never pass --cmd with anything destructive.

The output is an animated SVG with a real text layer, not a GIF, and it needs no external tools. Only meaningful when the project actually has a binary; the tape is a plain text file the author is expected to edit.

Exit codes

CodeMeaning
0Success
1Score below --min-score
2Bad arguments
3Not a valid repository
4--remote failed (API error, rate limit, private repo)
5Less than half the total weight could be scored — no total score is reported
7--base could not be resolved: shallow clone, unknown ref, no git

Codes 4 and 7 are deliberately distinct from code 1. A rate limit and a shallow clone are not quality regressions, and must never be reported as one. Say which happened; do not summarise either of them as "the check failed".

Making the calls repolish cannot

This is the part of the job that is actually yours, so it is worth being precise about where the tool stops.

repolish decides three different ways, and only two of them are strong:

  1. Facts. Does a LICENSE file exist, is there a workflow, how many headings are there. Filesystem and Markdown AST. Not arguable.
  2. Cross-references. claim-consistency takes the commands out of the README and checks them against the manifest and the filesystem. readme-install-consistency checks that the install command installs this package. These are joins between two sources of truth, not opinions — and they are the checks worth acting on first.
  3. Graded heuristics. readme-quickstart scores 0/4/6/8/10 from hand-curated substring lists. Most of the README checks have a list like that somewhere.

So the score is honestly a measure of whether the machinery a reader needs is present and whether the promises are true. It is not a measure of whether the writing is any good. repolish will happily give 10/10 to a quickstart made of the right keywords in the wrong order.

That is the gap you are here to close. Do not try to close it by rewriting. Work finding by finding:

FindingWhat a good fix looks likeThe failure mode to avoid
claim-consistencyMake the claim true (restore the script, add the npm script) or correct the text to what actually worksDeleting the line. That turns the check green and leaves the reader with no instructions at all
readme-title-taglineOne line saying what it does and who it is for, in the author's registerReplacing a specific tagline with "A blazingly fast, modern toolkit for…"
readme-quickstartThe shortest path from zero to one working result, with the prerequisite namedTurning it into a feature tour, or inventing a command you have not run
readme-usage-exampleA real example lifted from tests or examples/Inventing an API that does not exist. Check it compiles or runs
readme-lengthMove reference detail into docs/ and link itDeleting the detail
licenseTell the author their options and let them choosePicking one for them. It is a legal decision, not a formatting one
code-of-conductAsk for a real reporting addressA Contributor Covenant with a placeholder email promises a channel that does not exist
contributingTake build and test commands from the detected manifest<your build command here>
repo-description / repo-topics / repo-homepageDraft the text and hand it to the authorChanging repository settings yourself

Three rules that hold across all of them:

  • Cite the finding. Every edit you make should be traceable to an id and a file:line that repolish reported. If you cannot name one, you are redecorating.
  • Leave the voice alone. Match the surrounding register, list markers, heading depth and line width. A README that suddenly reads like documentation-as-a-service is a worse README even when it scores higher.
  • A higher score is not the goal. The goal is a repository a stranger can use. If a change would raise the number without helping that stranger, do not make it, and say why.

Why there is no model inside repolish

If you are wondering whether to suggest wiring an LLM into it: the scoring path is deliberately model-free, and that is not conservatism. A badge whose number moves because a model answered differently this morning is worth nothing, and the same commit has to produce the same score for the number to be comparable between repositories at all.

The intended arrangement is the one you are already in: repolish supplies evidence, you supply judgment. You have context it structurally cannot have — the codebase, the user's intent, this conversation. It has determinism you cannot have. Neither half is improved by moving it into the other.

Things to get right

  • Local and remote scores are not comparable. Without --remote, three discoverability checks drop out of the denominator. Say which one you ran.
  • Do not tune thresholds. .repolish.toml deliberately does not expose per-check thresholds; the check set and weights are frozen for v1 so scores stay comparable between repositories.
  • claim-consistency is the check to take seriously. It verifies that the commands the README promises actually exist — npm run build in package.json, make test as a real target, ./scripts/setup.sh as a real file. A README that fails on its first command is where readers leave. Fix those first, and fix them by making the claim true or by correcting it — never by deleting the line to make the check pass.
  • Report the numbers the tool gave you. If it says not scored, say not scored.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.