CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

docs-grounding-verifier

Use this skill to verify CLAIM-LEVEL grounding of a documentation page (or set of pages) against the source code. Activate when you have specific pages to check for factual accuracy -- not when sweeping a whole corpus (use docs-corpus-audit for that) and not when triaging a PR diff (use docs-sync for that). Trigger nouns: "is this doc accurate", "verify the page against the code", "fact-check this section", "any claims that drifted from source", "fact-checking", "grounding audit", "drift hunt", "claim verification". Returns per-claim verdicts (GROUNDED | PARTIAL | CONTRADICTED | UNSUPPORTED) with file:line evidence citations. Catches paragraph-level inaccuracies that page-level audit averages over -- e.g. a paragraph with 5 claims where 4 are grounded and 1 is fabricated. Does NOT modify files (returns advisory only); does NOT re-architect the docs; does NOT triage PRs.

Quality

87%

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

The canonical home for this skill is docs-grounding-verifier in microsoft/apm

SKILL.md
Quality
Evals
Security

Quality

Content

70%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 presents a coherent, well-validated pipeline: deterministic evidence retrieval, adversarial judgment, an alignment loop with a monotonic-improvement guard, and a ship gate. Its two real weaknesses are redundancy (the deterministic-Stage-2 rationale and sibling-boundary rules are each restated multiple times) and unshipped dependencies — the evals/ files cited in the ship gate and both out-of-bundle persona links do not exist in the bundle. Tightening the repetition and making every referenced path resolve would lift the content from good to excellent.

Suggestions

State the deterministic-Stage-2 rationale and the sibling-boundary rules once each (Architecture and Sibling contract respectively) and drop their restatements in 'Failure modes guarded against' and 'When NOT to activate' — this alone removes roughly a quarter of the body's tokens.

Ship the referenced evals/ files (trigger-evals.json, content-evals.json, run-evals.sh) or remove them from 'Ship gate' and 'Bundled assets' — the ship gate currently instructs running an eval-runner that is not in the bundle.

Replace the out-of-bundle ../../personas/*.persona.md links with in-bundle paths or inline the persona requirements, so every path a reader can follow actually resolves.

DimensionReasoningScore

Conciseness

Quotes: 'Stage 2 is the load-bearing design choice: evidence retrieval is DETERMINISTIC (grep + AST hints), not LLM... it cannot hallucinate support that the retriever did not find' reappears almost verbatim in Failure modes as 'Stage 2 is deterministic; judge sees only real evidence'. The sibling boundary is also stated four times (description-level routing, the Sibling contract table, 'When NOT to activate', and 'Dispatch collision' in Failure modes). Mostly efficient with no basic-concept padding, but the repeated design rationale and boundary restatements go beyond 'minor instances of over-explanation' (anchor 4) — the body could lose ~20-25% of its tokens without information loss, which is the anchor-3 case.

3 / 5

Actionability

Quotes: 'script: scripts/extract-claims.py', 'pipe to scripts/retrieve-evidence.sh', 'assets/judge-prompt.md -- Stage 3 adversarial judge prompt', with concrete JSON I/O shapes ('{"page", "claims":[{"id","text","section","keywords","expected_source_areas"}]}'). All three scripts and the judge prompt exist in the bundle and behave as described (verified: extract-claims.py emits prompts and a schema, retrieve-evidence.sh is pure ripgrep, verify-page.sh orchestrates). Not 5 because no end-to-end example invocation is shown, and the ship-gate instruction 'The eval-runner (see evals/) passes on the trigger evals' points at files (evals/run-evals.sh, trigger-evals.json, content-evals.json) that are absent from the bundle, so that step cannot actually be executed as written. Not 3 because the core pipeline guidance is executable, not pseudocode.

4 / 5

Workflow Clarity

Quotes: a six-phase pipeline (SCOPE -> EXTRACT -> RETRIEVE -> JUDGE -> SYNTHESIZE -> ALIGNMENT LOOP) with per-phase inputs and outputs; 'RE-RUN the pipeline on the same pages. The grounding_rate must MONOTONICALLY INCREASE between iterations or the loop has diverged -- stop and escalate'; UNSUPPORTED retry logic ('if retrieval_fix_suggestion is plausible, retry retrieval with the suggested keywords'); and a ship gate ('grounding_rate >= 0.9 on each verified page', 'Every CONTRADICTED claim cited a specific code file:line'). This is a batch operation that DOES have explicit validation steps, an error-recovery feedback loop, and a completion checklist — the anchor-5 pattern, so the batch-operation cap does not apply.

5 / 5

Progressive Disclosure

The body keeps a proper overview-to-bundle split and signals references clearly ('Bundled assets' section with per-file descriptions; scripts/ and assets/judge-prompt.md all exist one level deep). However, scoring against the actual bundle: 5 of the 9 referenced paths are phantom — 'evals/trigger-evals.json', 'evals/content-evals.json', 'evals/run-evals.sh' (no evals/ directory ships), and '[python-architect persona](../../personas/python-architect.persona.md)' / '[doc-writer persona](../../personas/doc-writer.persona.md)' (no personas directory exists at that relative path). Missing referenced files are more than 'minor organization gaps' (anchor 4), placing this in anchor 3 territory despite otherwise good structure.

3 / 5

Total

15

/

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.

The description is exemplary: it states a concrete capability, enumerates its output taxonomy with evidence format, gives seven natural trigger phrases, and explicitly disambiguates its two sibling skills with routing rules. Every clause is functional rather than padded. The only minor cost is length (~185 words), but each sentence carries trigger, boundary, or output information that the rubric rewards.

DimensionReasoningScore

Specificity

Quotes: 'verify CLAIM-LEVEL grounding of a documentation page (or set of pages) against the source code', 'Returns per-claim verdicts (GROUNDED | PARTIAL | CONTRADICTED | UNSUPPORTED) with file:line evidence citations', 'Catches paragraph-level inaccuracies that page-level audit averages over'. Multiple specific concrete actions with a fully enumerated output taxonomy — matches the anchor 'Lists multiple specific concrete actions; comprehensive coverage' exactly. Not 4 because there are no coverage gaps: input (pages), action (claim-level verification), output format (verdicts + citations), and explicit non-goals are all stated.

5 / 5

Completeness

What is explicit: 'verify CLAIM-LEVEL grounding... Returns per-claim verdicts... with file:line evidence citations... Does NOT modify files (returns advisory only)'. When is explicit: 'Activate when you have specific pages to check for factual accuracy -- not when sweeping a whole corpus... not when triaging a PR diff', plus concrete trigger phrases. Both halves are answered clearly and concretely, matching the anchor-5 example structure exactly. Not 4 because the 'when' is not merely present but doubly specified (activation conditions plus enumerated trigger nouns plus exclusion conditions).

5 / 5

Trigger Term Quality

Quotes: 'Trigger nouns: "is this doc accurate", "verify the page against the code", "fact-check this section", "any claims that drifted from source", "fact-checking", "grounding audit", "drift hunt", "claim verification"'. This is comprehensive natural-term coverage including synonyms ('fact-check this section' / 'fact-checking', 'grounding audit' / 'claim verification'), and the phrases are ones a user would naturally say. Not 4 ('a few natural terms missing') because seven varied trigger phrases spanning colloquial ('is this doc accurate') and operational ('grounding audit') registers are given; file extensions are not applicable to this docs-audit domain.

5 / 5

Distinctiveness Conflict Risk

Quotes: 'not when sweeping a whole corpus (use docs-corpus-audit for that) and not when triaging a PR diff (use docs-sync for that)', 'does NOT re-architect the docs; does NOT triage PRs'. The description names both sibling skills and routes would-be conflicts away from itself, establishing a clear niche (claim-level granularity on specific pages) with minimal conflict risk — the anchor-5 case. Not 4 because overlap risk is not just minor but actively disambiguated by explicit routing.

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: 2 suspicious

Warning

Total

15

/

16

Passed

Repository

microsoft/apm

Path

.agents/skills/docs-grounding-verifier/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.