docs-audit

Autonomous, report-only documentation review for Mastra docs. Use when auditing changed docs against source, validating contextual code examples or API coverage, checking canonical mastra-docs guidance, or running narrow deterministic checks.

Quality

81%

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

78%Weight 40%Scale 1-5

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

A tightly written, highly actionable audit workflow with clean separation of the report format and grading rubric into real one-level-deep reference files. The residual gaps are minor: some abstract directives in the completeness step and no explicit re-validation loop after checker failures.

Suggestions

Add an explicit feedback loop after step 7 (e.g., 'if the checker reports a new audited-target failure, re-run the affected page's evidence pass, then re-run the checker once') to raise workflow_clarity from 4 to 5.

Tighten the evidence-pass section by merging the repeated 'do not batch all references / issue serial reads' prohibitions into a single rule, trimming a few redundant clauses to push conciseness toward 5.

Dimension	Reasoning	Score
Conciseness	Dense procedural instruction with no explanations of concepts Claude already knows; every line prescribes audit behavior. Not 5 because the long 'do not' lists in the evidence-pass section (e.g., repeated prohibitions on batching and serial reads) could be trimmed; not 3 because there is no genuinely unnecessary explanation.	4 / 5
Actionability	Provides concrete directories, glob-based classifications, explicit batch limits ('at most two files and 500 requested lines', 'under 150 lines'), a citation format, and a copy-paste checker command. Not 5 because a few directives remain abstract (e.g., 'verify broad orientation, canonical ownership') and defer specifics entirely to external guides.	4 / 5
Workflow Clarity	Eight numbered steps in a clear sequence with a deterministic-check validation checkpoint (step 7) and explicit handling of truncation, ambiguous attribution, and scope limitations. Not 5 because there is no explicit re-validate/feedback loop after a checker failure, only guidance to record limitations; comfortably above 3 since checkpoints are mostly explicit.	4 / 5
Progressive Disclosure	The audit workflow lives in SKILL.md while the report format (references/AUDIT-REPORT.md) and audit rubric (references/RUBRIC.md) are cleanly split into real, one-level-deep files, clearly signaled by the 'References' and 'Scripts' sections. All referenced bundle paths exist, so navigation is easy — matches the anchor-5 structure.	5 / 5
	Total	17 / 20 Passed

Description

83%Weight 40%Scale 1-5

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

A strong description with a clear what/when structure and concrete, domain-specific triggers. Its only weaknesses are minor: slightly incomplete action coverage and a small overlap in wording with the related mastra-docs authoring skill.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions — 'auditing changed docs against source', 'validating contextual code examples', 'checking canonical mastra-docs guidance', 'running narrow deterministic checks' — with minor gaps such as report production. Not 5 because coverage is not comprehensive; not 3 because more than 1-2 specific actions are named.	4 / 5
Completeness	Explicitly answers both: 'what' via 'Autonomous, report-only documentation review for Mastra docs' and 'when' via an explicit 'Use when auditing... validating... checking... or running...' clause with four concrete trigger phrases. Matches the anchor-5 example structure exactly; 4 would require a less explicit 'when'.	5 / 5
Trigger Term Quality	Natural user phrases like 'documentation review', 'docs', 'audit', 'code examples', and 'API coverage' are present. Not 5 because common synonyms and variations (e.g., 'verify docs', 'review documentation changes') are missing; clearly above 3 since keyword coverage is good rather than partial.	4 / 5
Distinctiveness Conflict Risk	A clear Mastra-docs-audit niche with distinct audit/verify triggers. Not 5 because 'checking canonical mastra-docs guidance' mildly overlaps the sibling mastra-docs authoring skill's trigger surface; well above 3 given the domain-specific triggers.	4 / 5
	Total	17 / 20 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: 3b0d190

Reviewed: 5 days 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.