Audit a GitHub repo's README against best-practice patterns and produce a prioritized punch list of fixes. Runs a structured review covering hero presence, install-to-first-success length, "what is this in one sentence" clarity, audience-jargon match, scannability, and drift signals (stale versions, dead links, badge sprawl). Read-only diagnostic; opens a PR only when the user explicitly asks.
62
72%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/repo-doctor/skills/readme-doctor/SKILL.mdQuality
Discovery
67%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a well-crafted description with excellent specificity and a clear niche, listing concrete review dimensions and outputs. Its main weaknesses are the lack of an explicit 'Use when...' clause and somewhat technical trigger terms that may not match how users naturally phrase their requests. Adding explicit trigger guidance and more natural user-facing keywords would elevate this description significantly.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to review, audit, or improve a README, or mentions README quality, documentation review, or repo onboarding.'
Include more natural trigger terms users might say, such as 'improve my README', 'README feedback', 'documentation quality check', or 'is my README good enough'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: auditing README against best-practice patterns, producing a prioritized punch list, reviewing hero presence, install-to-first-success length, clarity, audience-jargon match, scannability, and drift signals (stale versions, dead links, badge sprawl). Very detailed and concrete. | 3 / 3 |
Completeness | The 'what' is thoroughly covered with specific review dimensions and outputs. However, there is no explicit 'Use when...' clause or equivalent trigger guidance. The description implies when to use it but never states it explicitly, which per the rubric caps completeness at 2. | 2 / 3 |
Trigger Term Quality | Includes some natural keywords like 'README', 'GitHub repo', 'dead links', 'badge', but misses common user phrasings like 'review my README', 'improve documentation', 'README quality'. The terms used are more expert/diagnostic jargon than what a typical user would naturally say. | 2 / 3 |
Distinctiveness Conflict Risk | Very clearly scoped to GitHub repo README auditing specifically, with distinct review criteria. Unlikely to conflict with general code review, documentation generation, or other skills due to its narrow and well-defined niche. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured, highly actionable skill that provides a thorough and concrete rubric for README auditing. Its main strength is the specificity of the scoring criteria and the clear four-phase workflow with appropriate safety gates. Its weaknesses are moderate verbosity (the intro and some explanatory passages could be tighter) and the lack of content splitting into supporting files for a skill of this length.
Suggestions
Extract the detailed rubric criteria (§2.1–2.9) into a separate RUBRIC.md reference file, keeping only a summary table in the main SKILL.md to improve progressive disclosure.
Tighten the opening paragraph — remove the philosophical framing ('Most README problems aren't typos...') and lead directly with what the skill does and its phases.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is well-written but verbose in places. The intro paragraph philosophizes about README problems rather than jumping to instructions. Section 1.5's audience inference explanation and the rubric score anchors (2.1–2.9) are detailed but justified given the complexity of the task. Some tightening is possible (e.g., the category descriptions in §1.4 could be a table). | 2 / 3 |
Actionability | The rubric is highly concrete: each criterion has a 1-5 scoring scale with specific anchors, the punch list has explicit priority rules (score ≤2 on §2.1–2.4 = P0), and the discovery phase specifies exact commands (`gh repo view`) and data to collect (manifest files, file tree depth 2, last 10 commits). The output format and prioritization logic are copy-paste actionable. | 3 / 3 |
Workflow Clarity | The four-phase workflow (Discovery → Audit → Punch list → Optional output) is clearly sequenced with explicit gates: mode selection before proceeding, category confirmation before auditing, user confirmation before any edits. Phase 4 has an explicit 'never auto-apply' safeguard and a confirmation step before surgery. The read-only default is a strong safety checkpoint. | 3 / 3 |
Progressive Disclosure | The content is entirely monolithic in a single SKILL.md with no bundle files. The rubric (§2.1–2.9) is substantial and could be split into a separate reference file. The skill references `repo-visuals` for shared patterns (operating modes, PR machinery) but doesn't link to it. For a skill of this length (~200+ lines), some content separation would improve navigability. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
7f66ce9
Table of Contents
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.