Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    README Audit

    1

    Checks a README for broken local links, missing sections and structure problems, with a fix for each. Free, local and read-only.

    Free

    Security scanned
    README Audit

    README Audit

    Example session with this skill installed

    /readme-audit README.md

    • Read your context and instructions
    • Compiled the readme audit
    • Generated the document

    Illustrative. The README is invented and has problems on purpose; the report below is what the script prints for it.

    README AUDIT (examples/bad/README.md: 4 medium, 10 info)
    21 lines, 5 headings, 4 links (0 web links not checked)
    
       MEDIUM line 2    broken-file-link
              [](docs/diagram.png)
              why: The file or folder it points to does not exist next to this README.
              better: Fix the path, restore the file, or remove the link.
       MEDIUM line 11   broken-file-link
              [usage guide](docs/usage.md)
              why: The file or folder it points to does not exist next to this README.
              better: Fix the path, restore the file, or remove the link.
       MEDIUM line 12   broken-anchor
              [Configuration](#configuration)
              why: No heading in this file matches that in-page link, so it goes nowhere.
              better: Fix the link or the heading (links use the heading text in lowercase with hyphens).
       MEDIUM line 20   unclosed-code-fence
              ```bash
              why: The code block is never closed, so everything after it renders as code.
              better: Add the closing fence.
       INFO   line 1    no-intro
              pipetrace
              why: There is no sentence under the title that says what the project is.
              better: Add one or two sentences: what it does and who it is for.
       INFO   line 1    missing-section-license
              (no heading about license)
              why: No heading looks like a license section.
              better: Name the license (and keep a LICENSE file).
       INFO   line 1    missing-section-contributing
              (no heading about contributing)
              why: No heading looks like a contributing section.
              better: Say how to report a problem or contribute, even if it is one line.
       INFO   line 1    no-license-file
              (next to the README)
              why: No LICENSE file was found in the same folder, so others may not be allowed to use the code.
              better: Add a LICENSE file with the license you choose.
       INFO   line 2    image-no-alt
              ![](docs/diagram.png)
              why: An image with no alt text is invisible to screen readers and shows nothing if the image fails to load.
              better: Describe the image in the square brackets.
       INFO   line 3    skipped-heading-level
              ### Install
              why: The heading jumps from level 1 to level 3, which breaks the outline for screen readers and tables of contents.
              better: Use level 2 here.
       INFO   line 5    code-block-no-language
              ```
              why: A code block with no language gets no highlighting and readers cannot tell what it is.
              better: Add a language after the opening fence, for example ```bash or ```python (use ```text for plain output).
       INFO   line 11   vague-link-text
              [here](docs/install.md)
              why: Link text such as here or link says nothing when read out of context.
              better: Use words that say where the link goes.
       INFO   line 14   duplicate-heading
              ## Usage
              why: The same heading appears on line 9, so in-page links to it go to the first one.
              better: Make the headings different.
       INFO   line 16   placeholder-text
              TODO: write this part.
              why: Leftover template text makes a project look unfinished.
              better: Fill it in or remove it.
    
    Limits: this checks structure, not meaning. It cannot tell whether the text is clear or correct, and it does not open web links, so a dead web address is not found. Section names are matched in English. In-page links follow the common heading-to-link rule, which some sites handle differently. A clean report is not a good README.
    

    Next steps

    • Fix the four MEDIUM findings first: they are broken for every reader.
    • Then add the missing sections and the language tags on the code blocks.

    diagram.png

    PDF · document

    Generated

    Example file from a real run - the skill writes it into your workspace.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    Check your README before anyone else reads it. Point it at a README.md (or the folder that holds it) and it reports what readers trip over: no title or no sentence saying what the project is, headings that skip a level, duplicate headings, code blocks with no language, an unclosed code block, images with no alt text, vague link text like "here", leftover TODO text, no install, usage, license or contributing section, no LICENSE file, links to local files that do not exist and in-page links that go nowhere. Every finding gives the line, the reason and how to fix it, with the serious ones (broken links, unclosed code block) first. A reference file explains each rule.

    What it reads and writes: only the README you name; it also checks whether the local files it links to (and a LICENSE file) exist. It writes nothing. It never opens a web address, so web links are counted but not checked. No network connection, no environment variables, nothing to install.

    Honest limits: it checks structure, not meaning, so it cannot tell whether the text is clear or correct. Section names are matched in English, and in-page links follow the common GitHub-style heading rule. A clean report is not a good README. Needs Python 3.9+.

    Needs Python 3.9+. Checks structure, not meaning. Web links are counted but never opened. Section names are matched in English. A clean report is not a good README.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Free forever

    No account required to browse

    Trust & safety

    Security scan

    Security scan passed 15 days ago

    • Free with an Agensi account

    Requires

    Python

    Permissions

    Terminal / Shell
    Read Files

    File Scopes

    <the
    README.md
    you
    name>

    Reads only the README you name and checks whether the local files it links to exist; it writes nothing, makes no network connection and reads no environment variables.

    Listed15 days ago
    Updated13 days ago

    What's inside

    Frequently Asked Questions

    No. It never contacts any address, so web links are counted but not checked. Links to local files and in-page links are checked.

    No. It only reports. The skill offers to apply fixes only after you say yes, and keeps the original text of anything it does not change.

    Title and intro, heading order and duplicates, code blocks (language and closing), image alt text, link text, placeholder text, install, usage, license and contributing sections, a LICENSE file, links to local files and in-page links.

    Yes: --fail-on medium (or info) exits with code 1 when a finding of that level or worse exists. --json prints the findings as JSON.

    New in Technical Documentation