Skip to main content
plugin

repo-doctor — Claude Code plugin: README audit

The repo-doctor plugin audits a repository README against a 9-point rubric and returns a prioritized fix list. It fits maintainers reviewing documentation before editing.

MIT ★ 20 updated 2026-10-15

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add anthropics/claude-plugins-community
/plugin install repo-doctor@claude-community
Open on GitHub

What repo-doctor does

repo-doctor audits a README inside Claude Code. It scans the repository, infers the project category and audience, then checks nine areas: the one-sentence explanation, hero visibility, install-to-first-success path, examples, scanability, audience language, and signs of drift. Every criterion receives a 1–5 score with supporting evidence.

The result is a chat-based punch list split into P0, P1, and P2. Each item gives the problem with line references, explains its relevance to the repository’s audience, and proposes a concrete change. The weighting adjusts for libraries, CLIs, frameworks, apps, specs, and personal projects.

Auto, Semi-auto, and Manual modes control how many choices Claude surfaces; Semi-auto is the default. The plugin is read-only unless you ask for a change. For a PR request, Claude shows the diff first and opens the PR only after that confirmation.

What it helps with

  • check whether the README explains the project clearly
  • shorten the path from installation to a first result
  • spot stale versions, dead links, and outdated screenshots
  • rank documentation fixes by urgency
  • prepare a PR after reviewing the diff

Example prompts for the agent

  • Audit the README at https://github.com/owner/name.
  • Check whether a first-time visitor can understand the project and install path.
  • Open a PR for the P0 and P1 items, but show me the diff first.

How to install repo-doctor

Plugin marketplace

/plugin marketplace add anthropics/claude-plugins-community
/plugin install repo-doctor@claude-community

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about repo-doctor

How do I install repo-doctor in Claude Code?

Run /plugin marketplace add anthropics/claude-plugins-community, then run /plugin install repo-doctor@claude-community. Restart Claude Code or start a new session so the plugin is discovered.

What does repo-doctor do?

It reviews a GitHub README against nine criteria, scores each one from 1 to 5, and produces a P0–P2 list of specific fixes.

Does repo-doctor edit the repository automatically?

No. It reads the repository by default. It opens a PR only after you explicitly request one, and it shows the diff first.

Source text

repo-doctor · MIT
# repo-doctor

A Claude Code plugin for **diagnosing GitHub README problems** — a structured audit against patterns that correlate with maintainer outcomes (hero presence, install-to-first-success length, "what is this in one sentence" clarity, audience-jargon match, drift signals), output as a prioritized punch list.

Currently ships one skill: **`readme-doctor`**. Read-only by default; opens a PR only when the user explicitly asks.

## Install

```
/plugin marketplace add livlign/claude-skills
/plugin install repo-doctor@livlign
```

After install, restart Claude Code (or start a new session) so the plugin's skills are discovered.

## How to run

> Audit the README at https://github.com/owner/name

Claude asks which operating mode to use (Auto / Semi-auto / Manual), scans the repo, infers its category and audience, walks a 9-criterion rubric, and produces a punch list grouped by priority:

- **P0 (blocking)** — issues that determine whether a stranger trying the repo bounces or stays.
- **P1 (high-leverage)** — fixable in an afternoon, meaningful payoff.
- **P2 (nice-to-have)** — polish.

Each item has one line on what's wrong (with line numbers), one line on why it matters for this repo's audience, and one line on a concrete fix.

By default the punch list lives in the chat. If you say *"open a PR for the P0/P1 items,"* Claude shows the diff first and then opens the PR upstream — never auto-applies.

## Operating modes

Same three modes as `repo-visuals` — Auto, Semi-auto (default), Manual. Mode affects how many decisions are silent vs surfaced; it does not skip rubric checks.

| Mode | What **you** decide | Typical back-and-forths |
|---|---|---|
| **Auto** | nothing | 0 |
| **Semi-auto** _(default)_ | category override (if Claude misclassified), which priority tier to act on | ~2 |
| **Manual** | every decision point | 5–8 |

## What the rubric covers

1. The "what is this" sentence
2. Hero presence above the fold
3. Install-to-first-success length
4. Concrete example before API docs
5. Audience-jargon match
6. Scannability
7. Drift signals (stale versions, dead links, badge sprawl, outdated screenshots)
8. "What this isn't" honesty (for non-1.0 / personal projects)
9. Contribution surface (for repos that want contributors)

Each criterion is scored 1–5 with cited evidence. Rubric weighting adapts to the inferred repo category (library, CLI, framework, app, spec, personal project).

## Layout

- [`skills/readme-doctor/SKILL.md`](./skills/readme-doctor/SKILL.md) — the audit skill (discovery → audit → punch list → optional PR).

© livlign · MIT · livlign/claude-skills

Similar plugins

All plugins for Writing and docs →

From the same set2

Project sponsors

Companies that keep this analytics open