- Home
- Skills
- Technical Documentation
- README Audit
Works with the AI Agents you already use
README Audit
Checks a README for broken local links, missing sections and structure problems, with a fix for each. Free, local and read-only.
Free
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

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
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+.
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Technical Documentation.
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
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
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
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 to use
No account required to browse
Trust & safety
Security scan
Security scan passed 15 days ago
- Free with an Agensi account
- Software
Python
Permissions
File Scopes
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.