docs-audit

Interactive documentation quality review for Mastra docs. Use when auditing, reviewing, or critiquing Mastra documentation; checking docs against source code; validating code examples, API accuracy, or property completeness; checking whether docs follow the styleguide and deterministic linters; or evaluating whether a beginner or agent can follow a doc to complete a job. This skill keeps humans in the loop with ask_user and submit_plan, then always runs an agent-build eval after approved fixes.

Quality

90%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

80%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable with concrete script commands and a well-sequenced 11-step workflow including validation feedback loops, plus sound progressive disclosure via real reference and script files. Its main weakness is conciseness, with some redundant rule restatements and a debugging aside that could be trimmed.

Suggestions

Trim the DO/DON'T ask_user selectionMode debugging aside and consolidate it into the 'Important rules' list to remove redundant guidance.

Remove or merge rules repeated between the numbered workflow steps and the final 'Important rules' section (e.g. 'Never edit before the audit report and approved plan' appears in both) to cut tokens.

Consider moving the long page-type classification list in step 2 into the referenced page-type guides, keeping only the dispatch rule inline.

Dimension	Reasoning	Score
Conciseness	The body is dense and mostly assumes Claude's competence with executable script invocations, but several passages pad rather than earn their place (e.g. the DO/DON'T ask_user selectionMode debugging aside and repeated restatements of rules already captured in 'Important rules'), so it is mostly efficient but could be tightened.	2 / 3
Actionability	It provides concrete, copy-paste-ready script invocations with exact flags (e.g. `init-run.sh --docs <files>`, `run-checks.sh --run-dir "$RUN_DIR" --docs <files>`) and specific ask_user code snippets, matching the fully-executable anchor.	3 / 3
Workflow Clarity	An 11-step 'Required workflow' is clearly sequenced with explicit validation checkpoints (report before editing, submit_plan approval, re-run checks after fixes, mandatory eval typecheck) and feedback loops for error recovery, fitting the score-3 anchor.	3 / 3
Progressive Disclosure	SKILL.md is an overview pointing to real one-level-deep references (RUBRIC.md, AUDIT-REPORT.md, STYLEGUIDE.md, page-type guides) and a scripts/ bundle with clearly signaled per-script usage, splitting content appropriately for easy navigation.	3 / 3
	Total	11 / 12 Passed

Description

100%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is specific, trigger-rich, and explicitly covers both what the skill does and when to use it, with a clearly scoped Mastra-docs niche. It is slightly long but the verbosity does not undermine clarity or distinctiveness.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions: 'auditing, reviewing, or critiquing', 'checking docs against source code', 'validating code examples, API accuracy, or property completeness', 'checking whether docs follow the styleguide and deterministic linters', and 'evaluating whether a beginner or agent can follow a doc' — matching the score-3 anchor of several specific concrete actions.	3 / 3
Completeness	It clearly states what the skill does and has an explicit 'Use when ...' trigger clause listing several triggering situations, so both what and when are explicitly answered.	3 / 3
Trigger Term Quality	Natural trigger terms users would say are well covered: 'auditing, reviewing, or critiquing', 'checking docs against source code', 'validating code examples, API accuracy, or property completeness', 'checking ... styleguide and deterministic linters', and 'evaluating whether a beginner or agent can follow a doc', giving good coverage of natural phrasings.	3 / 3
Distinctiveness Conflict Risk	It carves a clear niche scoped to Mastra documentation audits with distinct triggers (accuracy/completeness/followability checks vs source), making conflict with other skills unlikely.	3 / 3
	Total	12 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: mastra-ai/mastra
Path: .claude/skills/docs-audit/SKILL.md
Commit: 3b78ed9

Reviewed: 1 day ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

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.