docs-impact-classifier

Use this skill to classify the documentation impact of a pull request diff, returning one of three verdicts -- no-change, in-place edit, or structural change -- with bounded LLM cost. Activate as a sibling skill of docs-sync; the orchestrator calls this first, before any panel spawn, to keep cost floor at 1 LLM call when no docs work is needed. Reads .apm/docs-index.yml as the corpus map; never reads the full corpus.

Quality

79%

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

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/docs-impact-classifier/SKILL.md

Quality

Content

75%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 instruction skill with a clear funnel workflow and concrete commands, grep patterns, and an output schema. The gaps are the unspecified L2 persona prompt, the absence of an explicit error-recovery loop, and a few trimmable prose flourishes.

Suggestions

Provide the exact prompt text to send to the doc-analyser persona in Step 3, so the L2 call is fully copy-paste ready rather than leaving the persona invocation implicit.

Add an explicit validate->fix->retry loop for invalid verdict shapes (e.g. 'If the orchestrator rejects the JSON, re-issue with corrected scope_pages/structural_proposal'), to lift workflow clarity toward a feedback-loop model.

Trim flavor headings and rationale asides ('false-alarm killer', 'PR 1244 class') to recover a few tokens without losing the operational signal.

Dimension	Reasoning	Score
Conciseness	Dense and operational -- tables, bullet lists, and code/grep blocks with no padding about concepts Claude already knows -- but flavor headings ('false-alarm killer', 'PR 1244 class') and a few rationale sentences could be trimmed, keeping it just below a 5.	4 / 5
Actionability	Highly concrete with executable commands ('gh pr diff --name-only', 'gh pr diff --stat'), exact grep patterns, specific file paths, and a fully specified JSON output schema; the one gap is that Step 3 says 'invoke the doc-analyser persona' without giving the exact prompt to send.	4 / 5
Workflow Clarity	The L0->L1->L2 funnel is a clearly sequenced set of decision checkpoints and the Anti-patterns section acts as a verdict-shape checklist, but there is no explicit validate->fix->retry feedback loop, so it stops at 4 rather than 5.	4 / 5
Progressive Disclosure	Well-organized with clear section headers and no nested/deep references; as a single self-contained file with no bundle it is appropriately monolithic, but some subsections (rename heuristic, verdict semantics) could live in references if the file grows, so it is not a 5.	4 / 5
	Total	16 / 20 Passed

Description

83%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, specific description that clearly carves out a distinct niche and names concrete actions and outcomes. The main weakness is that the activation guidance leans on internal orchestration vocabulary rather than natural user trigger phrases.

Dimension	Reasoning	Score
Specificity	Names the domain and multiple concrete actions -- 'classify the documentation impact of a pull request diff', 'returning one of three verdicts -- no-change, in-place edit, or structural change', 'Reads .apm/docs-index.yml as the corpus map; never reads the full corpus' -- giving comprehensive, specific coverage of what the skill does.	5 / 5
Completeness	It explicitly answers 'what' (classify docs impact into three verdicts) and includes a 'Use this skill to...' trigger, but the 'when' is framed in orchestration terms ('the orchestrator calls this first, before any panel spawn') rather than a clean user-facing 'Use when...' trigger phrase, so it is not a full 5.	4 / 5
Trigger Term Quality	Contains natural triggers like 'documentation impact' and 'pull request diff', but a large share of the description is internal system jargon ('docs-sync', 'orchestrator', 'panel spawn', 'corpus map') rather than phrases a user would naturally say; common synonyms like 'docs'/'PR' are absent.	4 / 5
Distinctiveness Conflict Risk	A clear niche -- classifying PR documentation impact into three named verdicts as a sibling of docs-sync -- with distinct triggers and minimal overlap risk with other skills.	5 / 5
	Total	18 / 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: microsoft/apm
Path: .agents/skills/docs-impact-classifier/SKILL.md
Commit: 71a877c

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