docs-audit

Audits project documentation against the Diataxis framework and flags staleness.

Updated Jun 2, 2026
One-click install
npx skills add https://github.com/MohamedSayedK/omnigrid --skill docs-audit-mohamedsayedk
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: docs-audit
Source: https://github.com/MohamedSayedK/omnigrid/tree/main/assets/core/skills/docs-audit
Command: npx skills add https://github.com/MohamedSayedK/omnigrid --skill docs-audit-mohamedsayedk

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Project documentation drifts out of sync with code over time, and teams rarely know which docs are missing, stale, or misleading until a new contributor hits a wall. This Skill walks a repository's documentation and produces a structured findings report so gaps are visible and fixable. ## Core Features & Use Cases - Diataxis coverage scoring: Checks tutorials, how-to guides, reference material, and explanation docs against the four-quadrant Diataxis framework. - README and API doc checks: Verifies README sections (quick start, deployment, contributing), OpenAPI/Swagger spec presence, and endpoint documentation coverage. - Staleness detection: Cross-references git history and file dates against code changes to flag docs referencing removed frameworks, endpoints, or environment variables. - Use Case: Before a production launch, run the audit to discover that your README documents 0 of 8 environment variables and still references a framework the codebase no longer uses, then fix each flagged item. ## Quick Start Ask the assistant to run a docs audit on this repository and report which documentation areas pass, warn, or fail.

Frequently Asked Questions about docs-audit

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit project documentation for completeness?▼

Run a Diataxis-based audit that checks four quadrants: tutorials, how-to guides, reference, and explanation. The audit also reviews README sections, API specs, changelogs, and ADRs, then outputs a findings table with PASS, WARN, or FAIL per area.

What is the Diataxis framework for documentation?▼

Diataxis divides documentation into four quadrants: tutorials (learning-oriented), how-to guides (goal-oriented), reference (information-oriented), and explanation (understanding-oriented). It is used as a lens to score documentation coverage against project maturity rather than as a rigid checklist.

How do I detect stale or outdated documentation?▼

Staleness detection cross-references git log or file modification dates with recent code changes. It flags READMEs mentioning removed frameworks, API docs referencing deleted endpoints, and environment variable lists that no longer match runtime configuration.

Does the docs audit run dependency or security scans?▼

No, the audit only reads files and uses git history for staleness checks. It deliberately avoids package-manager audit commands, which belong to a separate dependency audit workflow.

What README sections should every project have?▼

At minimum a project README needs a description, a quick start, and deployment notes. Recommended additions include prerequisites, development setup, contributing guidelines, and a license statement.