agentleFS
Sign inStart free
me2reshme2resh/apexyard/.claude/skills/docs-audit/SKILL.md

docs-audit

Skill542 starsChanged 11 days agoMITView on GitHub

Diataxis docs audit — tutorials, how-to, reference, explanation; checks README, API docs, deployment guides, changelog, staleness.

  • Reads credentials

We split this skill into the rules it gives an agent

10 rules. 0 are common, 8 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 10 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Check README.md for these sections (each is pass/fail):

    line 28
  2. Very specific:

    Check for OpenAPI / Swagger spec (openapi.yaml, swagger.json)

    line 42
  3. Distinctive:

    Check for auto-generated docs (Swagger UI, Redoc, tsdoc, typedoc)

    line 43
  4. Distinctive:

    Check if endpoints in the code match the spec (any undocumented endpoints?)

    line 44
  5. Distinctive:

    Check for example requests and responses

    line 45
  6. Distinctive:

    Check if API docs mention endpoints/features that no longer exist

    line 58
  7. Distinctive:

    Check if environment variable docs list vars that are no longer used

    line 59
  8. Very specific:

    After printing the findings table, persist via the shared audit-history lib so the docs trend across runs becomes legible.

    line 86
  9. Distinctive:

    README is the minimum: Every project needs a README with at least: description, quick start, and how to deploy.

    line 131
  10. Distinctive:

    Diataxis is a lens, not a checklist: Don't fail a project for missing all four quadrants — most projects start with tutorials + reference …

    line 133

“Common” is measured: kept by at least 6 in 10 of the 10 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Writing: read docs/skills/shared/writing-rule.md before you write a durable artifact.

/docs-audit — Documentation Completeness (Diataxis)

Deep-dive documentation analysis using the Diataxis framework. Checks that docs cover all four quadrants (tutorials, how-to guides, reference, explanation) and are not stale. Invoke when /launch-check's documentation row shows WARN or FAIL.

Diataxis Framework

QuadrantPurposeWhat to look for
TutorialsLearning-oriented, guided first stepsGetting started guide, quickstart, "Hello World"
How-to guidesGoal-oriented, solving specific problemsDeployment guide, migration guide, troubleshooting
ReferenceInformation-oriented, accurate descriptionAPI docs, config reference, CLI flags, environment variables
ExplanationUnderstanding-oriented, why things workArchitecture overview, design decisions (AgDRs), ADRs

Process

Step 1: README quality

Check README.md for these sections (each is pass/fail):

SectionPresent?Quality check
Project descriptionOne paragraph explaining what this is and who it's for
PrerequisitesLanguage version, tools needed, accounts required
Quick startCopy-pasteable commands to get running locally in < 5 minutes
Development setupHow to set up the dev environment, run tests, lint
DeploymentHow to deploy to staging and production
ContributingHow to contribute (branch naming, PR process, code standards)
LicenseLicense type and link

Step 2: API documentation (if applicable)

  • Check for OpenAPI / Swagger spec (openapi.yaml, swagger.json)
  • Check for auto-generated docs (Swagger UI, Redoc, tsdoc, typedoc)
  • Check if endpoints in the code match the spec (any undocumented endpoints?)
  • Check for example requests and responses

Step 3: Operational docs

  • Deployment guide: how to deploy, what environment variables are needed
  • Runbook: what to do when things go wrong (overlap with /monitoring-audit)
  • Changelog: is there a CHANGELOG.md? Are releases documented?
  • Architecture overview: high-level diagram or description of components
  • AgDRs/ADRs: are technical decisions documented?

Step 4: Staleness detection

  • Compare README.md last-modified date with recent code changes
  • Check if API docs mention endpoints/features that no longer exist
  • Check if environment variable docs list vars that are no longer used
  • Flag docs that reference deprecated tools, libraries, or patterns

Step 5: Output

DOCS AUDIT — <project> @ <sha>

Diataxis coverage:
  Tutorials:   ✓ getting-started.md exists
  How-to:      ✓ deployment guide, ✗ migration guide, ✗ troubleshooting
  Reference:   ✓ OpenAPI spec (28 endpoints), ✗ env vars undocumented
  Explanation: ✓ 3 AgDRs, ✗ no architecture overview

| # | Area | Status | Finding |
|----|------|--------|---------|
| D1 | README | WARN | Missing "Contributing" section |
| D2 | API docs | PASS | OpenAPI spec matches code (28/28 endpoints) |
| D3 | Env vars | FAIL | 12 env vars in .env.example, 0 documented in README |
| D4 | Changelog | PASS | CHANGELOG.md updated with last 5 releases |
| D5 | Staleness | WARN | README references "Express" but code migrated to Fastify 3 months ago |

Documentation readiness: PARTIAL (1 fail, 2 warnings)

Persist the run + render trend

After printing the findings table, persist via the shared audit-history lib so the docs trend across runs becomes legible. See docs/agdr/AgDR-0019-audit-artefact-persistence.md.

Resolve project name + score + verdict

<project-name> from apexyard.projects.yaml (or basename + /handover reminder if unregistered).

Score: score = max(0, 100 - 25*critical - 10*high - 3*medium - 1*low). Verdict by worst-severity: critical/high → fail, medium → conditional, low/none → pass. Legacy "Documentation readiness" three-state: PARTIAL → conditional, MISSING → fail, COMPLETE → pass.

Persist + render

source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-audit-history.sh"

# Lowercase severity in the payload — the lib expects critical/high/medium/low/info.
payload=$(mktemp); cat > "$payload" <<'EOF'
{
  "schema_version": 1,
  "findings": [
    {"id": "D2", "severity": "high",   "status": "open", "summary": "No docs/how-to/ dir; recipes scattered in Slack"},
    {"id": "D3", "severity": "high",   "status": "open", "summary": "Env vars not documented in README (12 in .env.example)"},
    {"id": "D5", "severity": "medium", "status": "open", "summary": "README references Express; code migrated to Fastify 3 months ago"}
  ]
}
EOF

# Body: per templates/audits/docs-audit.md (Diataxis quadrants + README + staleness)
body=$(mktemp); cat > "$body" <<'EOF'
... (filled-in body — Diataxis groupings + README quality + staleness + Recommended priority) ...
EOF

ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
audit_run_persist "<project-name>" "docs-audit" "$ts" "fail" 60 "$body" < "$payload"
rm -f "$payload" "$body"

audit_render_trend "<project-name>" "docs-audit" 5

Opt-in commit

touch projects/<name>/audits/docs-audit/.audit-history-tracked

Rules

  1. README is the minimum. Every project needs a README with at least: description, quick start, and how to deploy. Everything else is a "should have."
  2. Check for staleness, not just existence. A README that exists but describes the wrong stack is worse than no README.
  3. Diataxis is a lens, not a checklist. Don't fail a project for missing all four quadrants — most projects start with tutorials + reference and add the rest over time.
  4. Auto-PASS for the ops repo itself. ApexYard's own docs are governed by its own process — this skill is for managed projects.
  5. Always persist via the lib. The persist step runs regardless of opt-in commit state.
  6. Severity vocabulary in the JSON is lowercase. The lib expects critical/high/medium/low/info.

Part of ApexYard — multi-project SDLC framework for Claude Code · MIT.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free