readme-polish

alirezarezvani/claude-skillsWriting & content

readme-polish is a skill in alirezarezvani/claude-skills, last changed 16 Nov 2026. It can run shell commands, reach the network, name web addresses and bundle scripts — read the findings before installing.

From the author
Use when an existing README must be upgraded, audited, or made scannable: polish/美化/升级/优化/打磨 README, add badges, mermaid, callouts, or collapsible sections, compare against top repos in the same ecosystem, or fix a plain/ugly first screen. Calibrates to the repo's own category, rewrites the hero and information hierarchy, and enforces a deterministic lint gate. Not for brand-new READMEs from scratch or hero-image design.

At a glance

What it can touch

How much a skill can do, not whether it is risky.

Pattern check

Nothing flagged

That isn't proof the skill is harmless.

Commit f8593c4 · 20 Nov 2026

How the check works

Pattern check: nothing flagged

That isn't proof the skill is harmless.

QAI Index

72/QI

We rate every listed skill the same way, from 0 to 100.

A guide to compare by, not a verdict on the skill.

How it's scored

How the QAI Index is scored

Adoption · up to 40
GitHub stars on the repo that holds the skill, shared among its skills, and copies of the skill in other repos.
Quality · up to 30
Our pattern check, the format check, a named licence and a description of a sentence or more.
Upkeep · up to 20
How recently the skill's folder changed.
Trust · up to 10
An official collection, or an organisation that has confirmed its domain with GitHub.

Get an email when its check changes.

Keep it with the other skills you use, installed with one command.

Install

Sign in to see how to install it

Free with Google or an email link, no password needed. Then pick your agent and copy its steps.

MIT
Licence
30.2k
Repo stars
Publisher
Files

What it can touch

Sign in to see the file and line behind each one

The summary at the top stays open to everyone. Signing in is free, with Google or an email link.

Pattern check

Pattern check: nothing flagged · commit f8593c4 · 20 Nov 2026

We checked every text file in this skill, at commit f8593c4 on 20 Nov 2026, against 45 published patterns such as download-and-run commands, hidden text and credential access. We don't run the skill, we don't read the web pages it points to, and we can't judge everything its instructions might lead an agent to do. In published tests, pattern checks like this one missed most malicious skills. Read the skill before you install it — especially anything it asks you to download or run.

How the check worksReport an incorrect finding

  • https://github.com/zhengqiuyang
  • https://github.com/alirezarezvani/claude-skills/tree/main/engineering/readme-polish
  • https://github.com/alirezarezvani/claude-skills
  • https://github.com/alirezarezvani/claude-skills.git
  • https://img.shields.io/badge/license-MIT-blue?style=flat-square)
  • https://img.shields.io/badge/python-3.10%2B-3776ab?style=flat-square)
  • https://img.shields.io/badge/version-1.2.0-informational?style=flat-square)
  • https://img.shields.io/badge/license-MIT-blue

Format check

Each agent reads SKILL.md a little differently. We check the file against each one's published rules; we don't run the skill in any agent.

  • Agent Skills specPasses

    The format our Agent Skills docs set out, held to the strictest version of each rule among the agents we check.

    • Note

      Anthropic's packaging script leaves these out: evals/. F8

      Fix: Delete them, or list them in .gitignore.

    • Note

      Reference files over 100 lines with no table of contents at the top: references/components.md (128 lines). B5

      Fix: Add a short list of the sections at the top of each.

  • Claude CodePasses

    Claude Code reads its own extra fields, ignores unknown ones, and still loads a skill whose frontmatter is broken, without its fields.

    • Note

      Anthropic's packaging script leaves these out: evals/. F8

      Fix: Delete them, or list them in .gitignore.

    • Note

      Reference files over 100 lines with no table of contents at the top: references/components.md (128 lines). B5

      Fix: Add a short list of the sections at the top of each.

  • Claude apps & API uploadPasses

    Uploading to claude.ai or the Claude API, or packaging with Anthropic's script, accepts only the six spec fields and stops on anything else.

    • Note

      Anthropic's packaging script leaves these out: evals/. F8

      Fix: Delete them, or list them in .gitignore.

    • Note

      The description is 424 characters. The claude.ai Help Center says 200 at most, though Anthropic's API docs and validator allow 1,024. D4

      Fix: If the claude.ai upload refuses it, trim the description to 200 characters.

    • Note

      Reference files over 100 lines with no table of contents at the top: references/components.md (128 lines). B5

      Fix: Add a short list of the sections at the top of each.

  • OpenAI (Codex & API)Passes

    Codex finds SKILL.md by its exact name and needs a description; OpenAI's Skills API checks the frontmatter against the spec and caps uploads.

    • Note

      Anthropic's packaging script leaves these out: evals/. F8

      Fix: Delete them, or list them in .gitignore.

  • VS Code & CopilotPasses

    VS Code reads skills one folder below .github/skills, .claude/skills or .agents/skills and falls back to the folder name when the name is missing or differs; GitHub's Copilot docs require the exact name SKILL.md.

    • Note

      Anthropic's packaging script leaves these out: evals/. F8

      Fix: Delete them, or list them in .gitignore.

SKILL.md

Files

Changelog

Newest first: each commit that changed its folder on GitHub, and each change to its listing here.

  1. Listed on QAI
  2. Updated: fix(readme-polish): no R003 on substrings, keep GitHub's emoji-headin… (29fafe2 (opens in a new tab))
  3. Updated: fix(readme-polish): exit-code contract, duplicate heading slugs, badg… (19d1da3 (opens in a new tab))
  4. Updated: feat(readme-polish): land community README-polish skill as a standalo… (d72e2ee (opens in a new tab))
  5. Updated: fix(readme-polish): support --sample for the JSON-output gate (a199e20 (opens in a new tab))
  6. Updated: feat(engineering): add readme-polish skill (ab33c96 (opens in a new tab))

QAI Index badge

Show this skill's QAI Index in a README or on a website. It links back to this page and changes when we refresh the catalog.

Preview of the QAI Index badge
[![QAI Index](https://qai.io/badge/skills/alirezarezvani/claude-skills/readme-polish.svg)](https://qai.io/skills/alirezarezvani/claude-skills/readme-polish)

More from alirezarezvani/claude-skills

SkillQAI IndexWhat it can touchPattern checkLicenceUpdated
71/QI
  • Runs shell commands
  • Names web addresses
  • +1 more
Pattern check: Nothing flaggedMIT30 Oct 2026
71/QI
  • Runs shell commands
  • Names web addresses
  • +1 more
Pattern check: Nothing flaggedMIT30 Oct 2026
65/QI
  • Runs shell commands
  • Names web addresses
  • +1 more
Pattern check: Nothing flaggedMIT27 Oct 2026
71/QI
  • Bundles scripts
Pattern check: Nothing flaggedMIT30 Oct 2026
71/QI
  • Runs shell commands
Pattern check: Nothing flaggedMIT3 Nov 2026
71/QI
  • Runs shell commands
  • Reaches the network
  • +2 more
Pattern check: Nothing flaggedMIT31 Oct 2026
All skills in alirezarezvani/claude-skills

Other Writing & content skills

Same category, most repo stars first.

SkillQAI IndexWhat it can touchPattern checkLicenceUpdated
76/QI
  • Instructions only
Pattern check: Nothing flaggedMIT27 Sept 2026
70/QI
  • Runs shell commands
Pattern check: Nothing flaggedMIT11 Jun 2026
academy-guideStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.

anthropics/skills

82/QI
  • Names web addresses

Pattern check: Nothing flaggedApache 2.0Updated 18 Aug 2026

82/QI
  • Names web addresses
Pattern check: Nothing flaggedApache 2.018 Aug 2026
discernment-nudgeAfter you give a substantive answer or draft that the user may act on — advice or recommendations, drafted artifacts such as goals, plans, pitches, proposals, or emails, estimates or projections, analysis or interpretation of data, factual claims they may rely on, or a multi-step argument — invoke this skill BEFORE finalizing your reply and then, if it applies, append 2-3 short follow-up questions, each tied to something specific in what you just produced, that help the user check key facts, probe the reasoning or assumptions, and notice missing context. Do this at most once per conversation. Skip it when the user asked a trivial how-to or simple lookup, wants a purely educational explanation, asked you only to format, convert, or assemble a file from content they provided, is writing code they will run, is doing creative writing or casual chat, or already asked you to double-check, cite, or review — the skill file explains these boundaries and the exact output format.

anthropics/skills

84/QI
  • Names web addresses

Pattern check: Nothing flaggedApache 2.0Updated 17 Aug 2026

84/QI
  • Names web addresses
Pattern check: Nothing flaggedApache 2.017 Aug 2026
70/QI
  • Runs shell commands
  • Reaches the network
  • +2 more
Pattern check: 3 items to reviewMIT19 Nov 2026
document-releaseRelease documentation audit. Use for: update docs after ship, document what changed. (gstack)

garrytan/gstack

70/QI
  • Touches credentials
  • +5 more

Pattern check: 3 items to reviewMITUpdated 19 Nov 2026

70/QI
  • Touches credentials
  • Runs shell commands
  • +4 more
Pattern check: 3 items to reviewMIT19 Nov 2026

Repo facts from GitHub on 20 Nov 2026. Files read at commit f8593c4.

QAI did not write these skills and is not affiliated with their authors unless a page says so. Logos and icons belong to their owners and are not a mark of approval. How we check