CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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.

68

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

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

An action-dense, well-sequenced skill body: concrete commands and grep patterns, a clear layered decision funnel with explicit exit conditions, and a strict output contract. The only weaknesses are minor redundancy around the in-place-resolved rule and a monolithic single-file structure that could offload some heuristics to references.

DimensionReasoningScore

Conciseness

The body is dense and operational throughout: no concept explanations Claude already knows, no library tours, and every section carries decision-relevant content. It is not a 5 because of minor trimmable redundancy -- the in_place_resolved rule is stated in the verdict table, a dedicated section, and the anti-patterns list, and the per-verdict cost columns are orchestrator context rather than skill instruction.

4 / 5

Actionability

Guidance is fully executable: concrete commands ("gh pr diff --name-only", "grep -rn <symbol> docs/src/content/docs/"), exact grep patterns per symbol class ("^@click.command", "--[a-z-]+"), a literal L0 decision rule with its return payload, a complete copy-ready JSON output schema, and a bounded context envelope. This matches the 'fully executable; copy-paste ready' anchor.

5 / 5

Workflow Clarity

The 3-layer funnel (L0 gate, L1 symbol grep, L2 LLM call) is clearly sequenced with explicit per-layer exit conditions ("The skill returns the verdict from the earliest layer that can decide"), the anti-patterns section is an explicit output-validation checklist ("orchestrator will reject"), and the output contract is unambiguous. Not 4: no validation gaps remain for this decision-only, non-destructive workflow.

5 / 5

Progressive Disclosure

No bundle files exist and none are needed; the body is self-contained with well-organized, clearly headed sections (Architecture, Steps, Verdict semantics, heuristics, Anti-patterns, Output contract). It does not reach 5: at ~155 lines it exceeds the short-skill exemption, and sections like the rename heuristic and verdict semantics table could arguably live in one-level-deep reference files.

4 / 5

Total

18

/

20

Passed

Description

76%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 specific, distinctive description with a clear what and an explicit (if orchestrator-oriented) activation clause. The main weakness is trigger phrasing: it lacks natural user-voice terms and common synonyms for the domain.

Suggestions

Add user-voice trigger phrasing, e.g. "Use when the user asks about the documentation impact of a PR, whether docs need updating after a change, or mentions docs-sync classification".

Include common synonyms and shorthands such as "PR", "docs update", and "doc changes" alongside "pull request diff" and "documentation impact" to improve natural-keyword coverage.

Trim orchestration detail ("to keep cost floor at 1 LLM call") in favor of user-relevant capability terms, since cost mechanics are already covered in the body.

DimensionReasoningScore

Specificity

The description names multiple concrete actions with explicit inputs and outputs: "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". It matches the comprehensive-coverage anchor; score 4 would require minor gaps, but coverage of what the skill does is complete.

5 / 5

Completeness

Both 'what' and 'when' are present: the what is fully explicit, and activation guidance ("Activate as a sibling skill of docs-sync; the orchestrator calls this first, before any panel spawn") satisfies the explicit-trigger requirement, so the completeness cap of 3 does not apply. It is not a 5 because the 'when' is system-directed rather than a concrete user-voice trigger phrase like 'Use when the user asks about doc impact of a PR'.

4 / 5

Trigger Term Quality

Relevant domain keywords are present ("documentation impact", "pull request diff", "docs", the three verdict names), but the phrasing is oriented to an orchestrator ("Activate as a sibling skill of docs-sync") rather than to natural user triggers, and common variations like "PR", "docs update", or "doc changes" are missing. This matches the 'some relevant keywords but missing common variations or synonyms' anchor rather than the good-coverage anchor at 4.

3 / 5

Distinctiveness Conflict Risk

The description carves a clear niche -- doc-impact classification with three named verdicts, a specific corpus map file (.apm/docs-index.yml), and an explicit sibling-skill position within docs-sync -- so it is unlikely to trigger for the wrong skill. This matches the 'clear niche with distinct triggers; minimal conflict risk' anchor.

5 / 5

Total

17

/

20

Passed

Validation

100%

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

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.