Works with
Packaged from the source skill for Claude, Codex and 4 more.
About this skill
README Polish reviews an existing repository README for clarity and credibility. It starts with the type of project and its intended audience, checks what the file can actually prove and selects presentation elements that serve that audience. A small utility checks selected structural and link issues without a network call.
Use this skill when
- A README has useful information, but readers cannot quickly tell what the project does or how to try it.
- Badges, screenshots, version statements or benchmark claims may be stale or unsupported.
- You want an audit or presentation recommendation before authorizing a rewrite.
What it can do
The workflow builds a fact list, examines comparable repositories when access is available and reorganizes the README around a quickstart, purpose, operation and limits. The packaged gate checks local links, heading anchors and selected badge, table and Mermaid conventions.
Static checks cannot confirm that a hosted badge is truthful or that every target platform renders the page correctly. A network-free run must disclose that external calibration was skipped. The diagram and layout rules are conventions to assess, not proof that a README communicates well. Confirm the rendered result and keep claims limited to evidence from the repository.
Typical workflows
- Audit the current page: identify first-screen gaps and unsupported components with line references, leaving the file unchanged.
- Polish a justified scope: retain accurate statements, rewrite the hierarchy and remove invented proof or decorative components that do not help the reader.
- Check delivery: resolve static findings, document deliberate exceptions and inspect headings, tables and diagrams on the intended hosting platform.
What is inside the skill
Section headings from the original SKILL.md (about 566 words of instructions). Read the full text in the source repository before installing.
- Before starting
- Modes
- Workflow
- Example
- Output
- Related skills
Bundled files
.claude-plugin/plugin.jsonREADME.mdevals/evals.jsonreferences/archetypes.mdreferences/checklist.mdreferences/components.mdscripts/check_readme.pyLICENSE
Example prompts
- Audit this existing README without editing it. Check whether a new user can identify the tool, find a working install command and understand its limits in the first screen; cite each issue by line.
- Polish this library README for developers evaluating adoption. Verify claims against the supplied repository, keep only real badges and examples, and make the quickstart easier to scan without adding a banner.
- Review this README after our heading changes. Check local links, repeated heading anchors and the Mermaid diagram, then list the remaining rendering checks for GitHub.
How to install Readme Polish
Claude Packaged
- Download the Claude package from the skill page. The ZIP contains one folder named after the skill, with SKILL.md and any bundled reference files.
- For Claude Code, unpack the folder into ~/.claude/skills/ to use it in every project, or into .claude/skills/ inside a repository to share it with your team.
- For Claude apps, upload the ZIP in the Skills section of the capabilities settings.
- Start a new session and describe the task in your own words. Claude picks the skill when the request matches its description.
Codex Packaged
- Download the Codex package. The ZIP contains one folder named after the skill, with SKILL.md and bundled resources.
- Unpack the complete folder into .agents/skills/ inside your repository, or into ~/.agents/skills/ for personal use. Preserve its relative reference-file paths.
- Start a new Codex session and invoke the skill by name or with $skill-name, or describe a matching task.
- AGENTS.md is separate project guidance. The ZIP does not generate or modify that file.
GPT Packaged
- Download the GPT package from the skill page.
- Create or edit a custom GPT (or a ChatGPT project) and paste the contents of SKILL.md into the instructions field.
- Upload the bundled reference files as knowledge so the GPT can consult them.
- Test with one of the example prompts from the skill page and adjust the instructions if your use case differs.
Gemini Packaged
- Download the Gemini package from the skill page.
- For a project, unpack the complete folder into .gemini/skills/ or .agents/skills/. For personal use, use ~/.gemini/skills/ or ~/.agents/skills/.
- Run /skills reload in Gemini CLI, then /skills list to check discovery. There is no need to paste the skill into GEMINI.md.
- Test a matching task and verify the referenced tools and files are available.
Cursor Packaged
- Download the Cursor package from the skill page.
- Unpack the complete skill folder into .cursor/skills/ or .agents/skills/ in your project. For personal local use, ~/.cursor/skills/ and ~/.agents/skills/ are also supported.
- Start a new Cursor session. Type / in Agent chat and select the skill name, or describe a matching task.
- Commit the skill folder and resources for team use. Personal local skills are not automatically available to remote agents or automation runs.
OpenCode Packaged
- Download the OpenCode package from the skill page.
- Unpack the complete folder into .opencode/skills/ in your project, or ~/.config/opencode/skills/ for personal use. OpenCode also supports .agents/skills/ and .claude/skills/ compatibility locations.
- Keep supporting files at their original relative paths. AGENTS.md is separate project-wide guidance and is not generated by this ZIP.
- Start OpenCode in the project and test a matching task with the model and permissions you use.
Permissions & security
Inspect the source, license and declared permissions before use. Read the scripts before running them. Review method
Readme Polish FAQ
What does the Readme Polish skill do?
Improve an existing README by checking its facts, first-screen hierarchy and local links. Includes a static gate and an audit-only mode; visual rendering still needs review.
Which AI agents can use Readme Polish?
Packages for Claude, Codex and 4 more are built from the same source instructions.
How do I install Readme Polish in Claude?
Download the Claude package from the skill page. The ZIP contains one folder named after the skill, with SKILL.md and any bundled reference files. For Claude Code, unpack the folder into ~/.claude/skills/ to use it in every project, or into .claude/skills/ inside a repository to share it with your team.
Who made Readme Polish and what is the license?
Readme Polish is published by zhengqiuyang under the MIT license. The source is https://github.com/alirezarezvani/claude-skills/tree/main/engineering/readme-polish. The catalog keeps the original attribution.
What permissions does Readme Polish need?
Declared permissions: read project files, write generated skill files. Risk level: low. Check the scripts in the source before running them.