auditing-readme

name	auditing-readme
description	Audit README.md files against best practices for repos, accounts, or orgs. Detects missing sections, stale links, inconsistent formatting, and convention violations. Use when reviewing README quality across one or many repos.
compatibility	Designed for Claude Code
metadata	{"argument-hint":"<scope> [target-or-glob]","allowed-tools":"Read, Grep, Glob, Bash, WebFetch, Agent","stability":"stable","content-hash":"sha256:5862812c4909f9f641e1c0b1f63f1d2d722677f68ecafa2304dc8f2e18bbd1ce"}

Audit README

Scope: $ARGUMENTS

Audit README.md files against scope-specific best practices and report findings.

Phase 1: Detect Scope and Targets

Parse $ARGUMENTS:

• repo — audit README.md in the current directory
• repo <owner/repo> — audit a specific remote repo's README
• repos <owner/pattern> — batch audit multiple repos (e.g., repos qte77/gha-*)
• account <username> — audit a GitHub user profile README
• org <orgname> — audit an organization profile README

Workflow Mode (batch repos scope)

When scope is repos with more than ~3 targets and the Workflow tool is available, fan the audit out in parallel instead of looping turn-by-turn:

1. Resolve the glob to a concrete list: gh repo list <owner> --json nameWithOwner, filtered by pattern.

2. Drive the bundled workflow (its instruction to call Workflow is the opt-in — no ultracode needed):

   Workflow({
     scriptPath: "${CLAUDE_PLUGIN_ROOT}/workflows/audit-repos.js",
     args: { repos: ["owner/a", "owner/b"],
             skillPath: "${CLAUDE_PLUGIN_ROOT}/skills/auditing-readme/SKILL.md" }
   })
   

   args is delivered to the script as a JSON string (the script parses it). Alternatively pass { owner, pattern, skillPath } and let the workflow's Discover phase resolve the list.

3. Render the returned perRepo findings and consistency observations with the Phase 4 format.

Fall back to the inline Phases 2–4 (one repo at a time) when the Workflow tool is unavailable. The workflow's agents are read-only, so the only permission to pre-grant is the Workflow tool.

Phase 2: Fetch READMEs

• Local repos: read README.md directly
• Remote repos: gh api repos/<owner>/<repo>/contents/README.md --jq '.content' | base64 -d
• Account profiles: gh api repos/<user>/<user>/contents/README.md --jq '.content' | base64 -d
• Org profiles: try profile/README.md first, fall back to root README.md in .github repo

Phase 3: Run Checklist

Base Repo Checklist — qte77 doc-structure canon

Derives from the canon contract (SoT) — audit against it, never redefine it.

#	Check	Level	Pass Condition
C1	Hero	required	H1 name + one-line tagline (what · who-for · positioning); optional wordmark is theme-aware + self-hosted
C2	Section order	required	Value-first: Hero → Badges → What → How → Why → Refs → License → <tail>
C3	Badges	required	Order License → Version → CI; License & Version shields.io static blue; License label carries the SPDX id (e.g. License: Apache-2.0, not bare license-MIT); Version linked to CHANGELOG.md; status badges native color; left-aligned, no <p align="center">
C4	What	required	## What present, ≤ ~7 reader-value bullets
C5	How	required	## How minimal run example + link out to docs/
C6	Why	required	## Why 2–4 lines (incumbent → gap → differentiation)
C7	Refs	required	## Refs links only, no prose
C8	License	required	## License SPDX id + link to LICENSE (not LICENSE.md)
C9	Front-door	recommended	each section answers its one question; depth links out to docs/, not inlined
C10	Screenshots	optional	if present: collapsed <details> at bottom of What, theme-aware, self-hosted at assets/images/
C11	Links valid	required	all [text](relative-path) links resolve; LICENSE file named LICENSE (not LICENSE.md)

GHA Extension (if action.yml/action.yaml exists)

#	Check	Level	Pass Condition
G1	Inputs table	required	Markdown table under heading containing "input"
G2	Outputs table	required	Markdown table or "no outputs" statement
G3	Usage YAML	required	Fenced yaml block with uses:
G4	What it does	required	Section with numbered steps
G5	Input column order	recommended	Name, Required, Default, Description

Account Profile Checklist

#	Check	Level	Pass Condition
A1	Tagline	required	Non-empty text within 5 lines of first heading
A2	Current focus	recommended	Section describing current work
A3	Featured projects	recommended	3+ repository links with descriptions
A4	Not stale	required	Updated within 6 months
A5	Scannability	recommended	Under 500 words

Organization Profile Checklist

#	Check	Level	Pass Condition
O1	File location	required	README at .github/profile/README.md
O2	Mission	required	Single-sentence purpose within 3 lines of H1
O3	Activities	required	Description of what the org does
O4	Projects	recommended	Links to key repos, grouped by domain
O5	CTA	required	"Get involved" section with actionable links
O6	Length	recommended	150-400 words

Phase 4: Report

Output a findings table per target:

## <repo-name>

| # | Check | Level | Status | Notes |
|---|-------|-------|--------|-------|

Summary: X/Y required pass, Z/W recommended pass.

Batch Summary

| Repo | Required | Recommended | Top Issue |
|------|----------|-------------|-----------|

Consistency Checks (batch only)

• Section order matches the canon (Hero → Badges → What → How → Why → Refs → License → tail)?
• Badge order/colors consistent (License → Version → CI; static blue / native status)?
• Version badge linked to CHANGELOG.md (flag a bare ![Version](…))?
• Canon section names used (## What / ## How / ## Why / ## Refs, not ## Resources)?
• License format consistent (LICENSE not LICENSE.md)?

Rules

• Never modify files during an audit — read-only
• Report facts, not opinions
• Derive from the canon; never invent divergent structure — qte77/qte77 docs/doc-structure.md is authoritative
• License file MUST be LICENSE (not LICENSE.md) — flag as FAIL if .md variant used