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

88%

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

85%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 well-structured autonomous audit workflow with clear sequencing, a built-in deterministic validation step, and clean progressive disclosure to verified reference files. Verbosity in the negative guardrails and delegation of the report template are the only minor weaknesses.

Dimension	Reasoning	Score
Conciseness	The body assumes Claude's competence with no concept padding, but the dense series of negative guardrails ('Do not retry with glob variants...', 'Never call conversation recall...') could be tightened in places to trim tokens.	4 / 5
Actionability	It provides a concrete executable command ('bash .claude/skills/docs-audit/scripts/run-checks.sh --docs ...'), specific content directories, a classification taxonomy, and named reference files, with only minor gaps since the report template is delegated to a reference.	4 / 5
Workflow Clarity	An explicit 8-step sequence runs from scope determination through a deterministic checker (validation) to a final report, with feedback loops for truncated reads and a Rules checklist, satisfying the batch-operation validation requirement.	5 / 5
Progressive Disclosure	The body is an overview/workflow that points to real one-level-deep references (RUBRIC.md, AUDIT-REPORT.md) and a script (run-checks.sh), all listed in dedicated References/Scripts sections and confirmed to exist in the bundle.	5 / 5
	Total	18 / 20 Passed

Description

92%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, third-person description that answers both what and when with concrete trigger phrases and a clearly scoped Mastra-specific niche. The only minor weakness is a couple of technical trigger terms that users may not naturally say.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete audit actions — 'auditing changed docs against source', 'validating contextual code examples or API coverage', 'checking canonical mastra-docs guidance', 'running narrow deterministic checks' — giving comprehensive coverage of the audit pipeline rather than a single generic verb.	5 / 5
Completeness	It explicitly states what the skill does ('Autonomous, report-only documentation review for Mastra docs') and gives an explicit 'Use when' clause with concrete trigger phrases, satisfying both halves clearly.	5 / 5
Trigger Term Quality	The 'Use when' clause surfaces natural phrases like 'auditing changed docs against source' and 'API coverage', but terms such as 'narrow deterministic checks' and 'canonical mastra-docs guidance' are technical and a few common synonyms are missing.	4 / 5
Distinctiveness Conflict Risk	The 'Mastra docs' niche plus the 'report-only' / 'auditing' framing carves out a distinct purpose with minimal overlap risk against the related mastra-docs authoring skill.	5 / 5
	Total	19 / 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: 8174f1c

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.