CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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.

70

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

73%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-engineered orchestration body: the process is concrete, validation-first, and loaded with feedback loops, and the bundle files it leans on are real. Its weaknesses are runtime-irrelevant padding (framework acronym strings, repeated trigger-boundary prose, a provenance section) and an Evals section referencing files that are not actually bundled.

Suggestions

Remove or compress the non-runtime sections: the Provenance section, the repeated trigger-boundary statements (keep only the sibling-contract table), and the unexplained 'A1/A8/A9/R3/S7' framework labels that Claude has no way to resolve.

Either bundle the evals/ files (content-evals.json, trigger-evals.json, README.md) referenced in the Evals section, or drop that section -- currently every reference in it is dangling.

Inline a minimal concrete example of the wave dispatch (one substituted subagent-prompt-template invocation and one example 6-8 page scope partition) so the core fan-out step is executable from the body alone.

DimensionReasoningScore

Conciseness

The body is mostly efficient but carries several unnecessary or padded passages: the unexplained framework string 'A1 PANEL + WAVE EXECUTION + S7 DETERMINISTIC TOOL BRIDGE + A8 ALIGNMENT LOOP + A9 SUPERVISED EXECUTION', the cryptic 'that's R3 EXTRACT in reverse', a trigger-boundary statement repeated three times (intro, sibling contract, boundary section), and a non-runtime Provenance section. These are multiple instances rather than the 'minor instances' of the 4 anchor, so 3 fits best.

3 / 5

Actionability

Concrete, executable guidance is present throughout: 'uv run apm <verb> --help' for CLI, 'grep -n src/apm_cli/' for symbols, 'python -c "import ..."' for module shape, 'scripts/scan-cross-corpus-drift.sh' with 'Run --help for pattern list', plus a real bundled subagent prompt template. It falls short of the 5 anchor because the wave-dispatch mechanics and an example scope partition are only pointed at via the template asset rather than shown.

4 / 5

Workflow Clarity

The 8-step process is clearly sequenced with explicit validation checkpoints and feedback loops at every stage: 'Validate every return against the schema; reject malformed JSON', a deterministic cross-corpus post-pass, an alignment loop with 'bounded: max 2 redrafts per wave' plus maintainer escalation, and a probe step that asks the maintainer when a required target is missing. As a batch/git-writing skill it does include validation, so the <=3 cap does not apply; the 5 anchor's 'explicit validation steps; feedback loops for error recovery' is matched.

5 / 5

Progressive Disclosure

Good structure with a dedicated 'Bundled assets' section and one-level-deep references that all resolve (assets/subagent-prompt-template.md, assets/panelist-return-schema.json, scripts/scan-cross-corpus-drift.sh -- verified present). However the 'Evals' section points at evals/content-evals.json, evals/trigger-evals.json, and evals/README.md, and step 8 references ../pr-description-skill/SKILL.md -- none of which exist in the bundle, leaving dangling references that keep it below the 5 anchor.

4 / 5

Total

16

/

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.

An exemplary description: concrete capability statements, a rich set of natural trigger phrases, explicit what/when structure, and a well-drawn boundary against the sibling docs-sync skill. Internal jargon like 'S7-verified' and 'Wave-batched' is slightly opaque but does not dilute the trigger or capability signal.

DimensionReasoningScore

Specificity

The description lists multiple concrete actions -- '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' plus 'Wave-batched and S7-verified' -- with comprehensive coverage of the skill's capability. It matches the 5 anchor ('multiple specific concrete actions; comprehensive coverage') rather than 4 because there are no material gaps in what the skill does.

5 / 5

Completeness

Both 'what' (corpus-wide regrounding pass against source code with surgical fixes) and 'when' ('Activate when the maintainer wants a WHOLE-CORPUS audit... typical triggers include...') are explicit and paired with concrete trigger phrases, matching the 5 anchor exactly.

5 / 5

Trigger Term Quality

Quotes natural user phrasings directly: 'audit the docs', 'reground the corpus', 'check every page against code', 'pre-release docs sweep', 'the docs have drifted everywhere', and 'we just reshaped the TOC, find dead links'. This is comprehensive synonym coverage matching the 5 anchor; nothing common is missing.

5 / 5

Distinctiveness Conflict Risk

The description explicitly fences off its sibling -- '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)' -- and lists non-goals ('Does NOT auto-merge, does NOT push...'). Clear niche with distinct triggers and minimal conflict risk, matching the 5 anchor rather than 4.

5 / 5

Total

20

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

relative_links

Relative link issues: 8 suspicious

Warning

Total

15

/

16

Passed

Repository

microsoft/apm

Path

.agents/skills/docs-corpus-audit/SKILL.md

Reviewed

Table of Contents

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.