Name: docs-corpus-audit
Rating: 72.8 (1 reviews)
Author: microsoft

docs-corpus-audit

Use this skill to run a holistic regrounding pass on the entire microsoft/apm documentation corpus against current source code, page-by-page, and emit surgical fixes for stale claims. Activate when the maintainer wants a WHOLE-CORPUS audit (not per-PR review) -- typical triggers include "audit the docs", "reground the corpus", "check every page against code", "pre-release docs sweep", "the docs have drifted everywhere", or "we just reshaped the TOC, find dead links". Wave-batched and S7-verified; scales to the full ~112-page corpus in ~10 minutes wall-time. This is a SIBLING to docs-sync, not a replacement: docs-sync is per-PR (triggered by a diff); this skill is per-corpus (triggered by a maintainer ask). They share agent personas, schemas, and the docs index, but their triggers MUST NOT collide. Does NOT auto-merge, does NOT push without maintainer review, and does NOT replace per-PR drift detection.

Quality

90%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

81%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, actionable body with an explicit multi-step workflow, validation/feedback loops, and one-level-deep references to real bundle files. It is held back from top marks by light verbosity from internal branding terms and references to files outside the bundle.

Suggestions

Trim the A1/A8/A9/S7/R3 taxonomy labels (or define them once) to reduce token overhead for readers unfamiliar with the internal scheme.

Dedupe the sibling/trigger-boundary content between the description and body so the same disambiguation is not stated twice.

Note which referenced paths (evals/, ../../agents/, ../pr-description-skill/) are external substrate vs. bundled, so a reader can tell what is and isn't expected to ship with the skill.

Dimension	Reasoning	Score
Conciseness	Largely lean and procedural with no explaining of concepts Claude already knows, but the internal taxonomy branding ('A1 PANEL', 'A8 ALIGNMENT LOOP', 'S7', 'A9', 'R3') and the repeated sibling/trigger-boundary content add tokens that could be trimmed; not a 5 because of these minor over-explanation instances.	4 / 5
Actionability	Provides concrete executable commands ('uv run apm <verb> --help', 'grep -n src/apm_cli/', 'python -c "import ..."') and real script/asset paths, but placeholders like '<verb>' and the deferred prompt template keep it just short of fully copy-paste-ready; not a 3 because the guidance is genuinely executable.	4 / 5
Workflow Clarity	The 8-step process is clearly sequenced with explicit validation checkpoints — PROBE preconditions, schema validation with 'reject malformed JSON', and the ALIGNMENT LOOP re-grep + bounded re-dispatch (max 2 redrafts) — providing the feedback loops a batch operation requires.	5 / 5
Progressive Disclosure	A dedicated 'Bundled assets' section clearly signals one-level-deep references to real files (subagent-prompt-template.md, panelist-return-schema.json, scan-cross-corpus-drift.sh), but several referenced paths (evals/, ../../agents/*.agent.md, ../pr-description-skill/SKILL.md) are not present in the bundle, leaving minor navigation gaps.	4 / 5
	Total	17 / 20 Passed

Description

100%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 precise, well-scoped description that states concrete capabilities, enumerates natural trigger phrases, and explicitly bounds the skill against its sibling to avoid dispatch collision. It is somewhat verbose but every clause earns its place.

Dimension	Reasoning	Score
Specificity	Names the domain and lists multiple concrete actions — 'run a holistic regrounding pass', 'page-by-page' audit 'against current source code', and 'emit surgical fixes for stale claims' — with comprehensive coverage; not a level-4 gap since the actions are specific and complete.	5 / 5
Completeness	Explicitly answers both 'what' ('run a holistic regrounding pass... emit surgical fixes') and 'when' ('Activate when the maintainer wants a WHOLE-CORPUS audit... typical triggers include...') with concrete trigger phrases, matching the top anchor.	5 / 5
Trigger Term Quality	Six natural trigger phrases users would actually say are enumerated — 'audit the docs', 'reground the corpus', 'check every page against code', 'pre-release docs sweep', 'the docs have drifted everywhere', 'we just reshaped the TOC, find dead links' — covering synonyms and variations.	5 / 5
Distinctiveness Conflict Risk	Carves a clear niche — per-corpus vs per-PR — and explicitly disambiguates from the sibling docs-sync ('triggers MUST NOT collide', 'Does NOT replace per-PR drift detection'), giving minimal conflict risk.	5 / 5
	Total	20 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 8 suspicious	Warning

	Total	15 / 16 Passed

Repository: microsoft/apm
Path: .apm/skills/docs-corpus-audit/SKILL.md
Commit: 71a877c

Reviewed: ~4 hours 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.