Public Readme Polisher

Public README Polisher

Polish the README as the repo's public front door: credible, scannable, actionable, and claim-safe.

Use When

• a README feels plain
• a repo needs a public first impression
• a docs landing page needs clearer value, install path, or proof
• a visual asset could make the repo easier to understand

Process

1. Audit repo truth: purpose, install path, tests, license, security, CI, docs,

examples, and public claim boundaries.

1. Define the public promise in one paragraph: who it helps, what it gives

them, and what it does not guarantee.

1. Improve the first viewport: title, optional hero, badges, concise opening,

quick action, and a scannable "what you get" table.

1. Add scanning structure: quick start, workflow diagram when useful, proof or

sources near the claim, and links to deeper docs.

1. Validate links, images, alt text, docs scan, tests, and the scorecard below.

Visual Asset Rules

• Use one purposeful hero only when it clarifies the repo.
• For generated images: no embedded text, no logos, no watermarks.
• Inspect the image before committing; reject generated image with readable fake

text, broken UI, mascot drift, or misleading claims.

• Save README assets under assets/readme.
• Add alt text that explains the image function.

Claim Safety

• Cite official sources for factual pricing, cache, legal, API, or security

claims.

• Say "patterns that worked for us" for experience-based recommendations.
• Avoid guaranteed savings, official endorsement, universal safety claims, or

"works for every workflow" language.

• Keep related tools optional unless the repo truly depends on them.

Scorecard

Score each category 0-2. Pass at 13/16 or higher.

| Category | 2 means | | --- | --- | | First-viewport signal | repo purpose, visual tone, badges, and install path are clear without scrolling | | Audience/value clarity | reader knows who it is for and what problem it solves | | Scannability | tables, bullets, headings, and diagrams make scanning easy | | Actionability | quick start and next links are concrete and current | | Trust/proof | sources, CI, license, tests, and safety boundaries support the claims | | Visual polish | assets feel intentional, domain-fit, and not generic stock decoration | | Accessibility/asset hygiene | alt text, local paths, file size, and image rendering are sane | | Claim safety | claims are bounded, sourced where needed, and public-safe |

Automatic blockers: private paths, secrets, broken local links, missing install path, false or guaranteed claims, generated image with readable fake text, missing alt text, failing docs scan.

Common Mistakes

• Making a marketing page that hides the actual install/use path.
• Adding a pretty image that does not explain the repo.
• Moving official citations away from the claims they support.
• Replacing precise safety boundaries with vague hype.
• Claiming completion without running the scorecard.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 100yenadmin
• Source: 100yenadmin/fable-token-saving-skills-orchestrator
• License: MIT

Install and usage instructions live in the source repository linked above.