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

92%

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

100%Weight 40%Scale 1-3

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 lean, highly actionable decision funnel with concrete commands, grep patterns, an exact return schema, and explicit validation checkpoints throughout; it is well-organized and self-contained with no padding or unnecessary concept explanation.

Dimension	Reasoning	Score
Conciseness	The body is dense and purposeful: architecture summary, three funnel layers with exact grep patterns and commands, a full JSON return schema, a verdict-semantics table, anti-patterns, and an output contract. It does not explain concepts Claude already knows, and every section carries decision-relevant content. It matches the 'lean and efficient; every token earns its place' anchor rather than the score-2 'could be tightened' anchor.	3 / 3
Actionability	It gives concrete, executable guidance: specific commands ("gh pr diff --name-only", "gh pr diff --stat"), exact grep patterns ("^@click.command", "--[a-z-]+", "raise ... Error("), and a complete copy-paste-ready JSON schema for the verdict. The L0 rule is a deterministic decision predicate rather than runnable code, which is justified by its purpose, so this is not the pseudocode-penalized score-2 anchor.	3 / 3
Workflow Clarity	The three layers (L0 -> L1 -> L2) are explicitly sequenced, each with its own exit condition and verdict, and there are explicit validation checkpoints: the L1->L2 gate ("If L1 found zero candidate pages AND zero schema/CLI/flag changes: return no_change") and the in-place-resolved downgrade rule. The anti-patterns section acts as a verdict-shape checklist and the output contract enforces a final validation, matching the 'clear sequence with explicit validation steps' anchor.	3 / 3
Progressive Disclosure	No bundle files exist (references/, scripts/, assets/ are absent) and none are referenced, so all content is appropriately self-contained in SKILL.md; per the simple-skills note, well-organized inline content with no external references can score 3. The body is cleanly sectioned (Architecture, Steps 1-3, Verdict semantics, heuristics, Anti-patterns, Output contract), so navigation is easy.	3 / 3
	Total	12 / 12 Passed

Description

85%Weight 40%Scale 1-3

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 specific, distinctive, and complete with explicit trigger and activation guidance; its only weakness is trigger-term naturalness, where internal jargon crowds out the phrasings a user would actually say.

Suggestions

Add user-natural trigger phrasing alongside the jargon, e.g. 'Use when checking whether a PR requires documentation updates or a docs sync'.

Soften internal terms (docs-sync, panel spawn, orchestrator) or briefly gloss them so the trigger is intelligible without the surrounding system context.

Consider listing the natural synonyms for the verdicts (e.g. 'no docs change needed') so the description surfaces terms users actually voice.

Dimension	Reasoning	Score
Specificity	Names concrete actions: "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" and specifies the corpus map ("Reads .apm/docs-index.yml"). This matches the 'lists multiple specific concrete actions' anchor, not the score-2 anchor that only names a domain.	3 / 3
Completeness	It answers 'what' explicitly and opens with the trigger phrasing "Use this skill to classify..." plus activation guidance ("Activate as a sibling skill of docs-sync; the orchestrator calls this first"), satisfying the explicit-trigger requirement for a 3. It is not capped at 2 because an explicit 'Use this skill to...' clause is present alongside the orchestration 'when'.	3 / 3
Trigger Term Quality	It includes relevant terms ("documentation impact of a pull request diff", the three verdict names) but leans on internal jargon ("docs-sync", "panel spawn", "orchestrator", ".apm/docs-index.yml") and misses common user phrasings like 'does this PR need docs updates'. It is better than the jargon-only score-1 anchor but lacks full natural-term coverage.	2 / 3
Distinctiveness Conflict Risk	It carves a clear niche as the cost gate for the docs-sync system with distinct, system-specific triggers ("cost floor at 1 LLM call", "never reads the full corpus"), making conflict with other skills unlikely. This matches the 'clear niche with distinct triggers' anchor.	3 / 3
	Total	11 / 12 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: 634f7b6

Reviewed: 8 days 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.