Name: docs-corpus-audit
Rating: 70.39999999999999 (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

86%

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

77%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.

The body is a well-structured, actionable orchestration guide with an explicit validated workflow and excellent progressive disclosure into real bundle files. Its main weakness is conciseness: the docs-sync sibling relationship and persona composition are repeated across sections and could be consolidated.

Suggestions

Consolidate the docs-sync sibling/trigger-boundary material: it appears in the intro paragraph, the 'Sibling contract' section, and the Process -- state it once and cross-reference to reduce redundancy.

Merge persona-composition detail between 'Architecture invariants' and the 'Roster' table so each persona's role is described in one place rather than two.

For orchestration-level Process steps (e.g. WAVE-PLANNER partitioning, dispatch), add the specific command or template-substitution snippet where feasible to lift actionability from mostly-executable to copy-paste ready.

Dimension	Reasoning	Score
Conciseness	Mostly efficient with no basic-concept padding, but the docs-sync sibling relationship and trigger boundary is stated in the intro and restated in the 'Sibling contract' section, and persona composition is repeated across 'Architecture invariants' and the Roster table -- more than minor redundancy that could be tightened.	3 / 5
Actionability	Provides concrete executable commands ('uv run apm <verb> --help', 'grep -n src/apm_cli/', 'python -c "import ..."') plus real prompt-template and schema assets, but several process steps ('dispatch one task per scope', 'partition pages') remain orchestration-level rather than literal commands.	4 / 5
Workflow Clarity	Explicit 8-step numbered Process with validation checkpoints (PROBE preconditions, schema validation rejecting malformed JSON, ALIGNMENT LOOP feedback bounded to max 2 redrafts) -- a batch operation with full validation and feedback loops.	5 / 5
Progressive Disclosure	Clear sectioned overview delegates heavy detail one level deep to real, substantive bundle files (subagent-prompt-template.md, panelist-return-schema.json, scan-cross-corpus-drift.sh) with a 'Bundled assets' inventory; all in-bundle references resolve and content is appropriately split rather than inlined.	5 / 5
	Total	17 / 20 Passed

Description

95%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.

The description is strong across all dimensions: it states concrete actions, lists comprehensive natural trigger phrases, explicitly covers both what and when, and clearly disambiguates from its sibling skill docs-sync with explicit trigger boundaries and negative scope.

Dimension	Reasoning	Score
Specificity	Names several concrete actions ('regrounding pass', 'emit surgical fixes', 'page-by-page', 'Wave-batched and S7-verified') but 'regrounding pass' leans on domain jargon, leaving minor gaps versus fully comprehensive coverage.	4 / 5
Completeness	Explicitly answers both what ('run a holistic regrounding pass... emit surgical fixes for stale claims') and when ('Activate when the maintainer wants a WHOLE-CORPUS audit... typical triggers include...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Comprehensive natural trigger phrases a maintainer would actually say ('audit the docs', 'reground the corpus', 'check every page against code', 'pre-release docs sweep', 'the docs have drifted everywhere', 'find dead links'), including synonyms.	5 / 5
Distinctiveness Conflict Risk	Clear niche with explicit disambiguation ('SIBLING to docs-sync, not a replacement', 'triggers MUST NOT collide') and negative boundaries ('Does NOT auto-merge, does NOT push without maintainer review'), minimizing conflict risk.	5 / 5
	Total	19 / 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: .agents/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.