docs-impact-architect

Use this skill when the docs-impact-classifier returns a structural verdict, signalling that the documentation TOC must change to accommodate the PR. Proposes TOC deltas (new pages, moves, merges) and emits new-page outline stubs that the doc-sync panel later fleshes out. Holds the 3-promise narrative (consume / produce / govern) and the persona ramps as hard constraints.

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

92%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 skill body is concise, highly actionable, and sequences a clear five-step workflow with an explicit validation checkpoint and feedback loop. Its only weakness is progressive disclosure: it is a self-contained monolithic file with no reference structure.

Suggestions

Consider moving the detailed structural-shape catalog table and/or the full YAML/JSON schemas into a reference file (e.g. references/toc-delta-templates.md) with a one-line pointer from Step 3, keeping SKILL.md as a tighter overview.

If the skill is intended to stay self-contained, trim toward the sub-50-line simple-skill range so the lack of references aligns with the rubric's exemption rather than reading as monolithic.

Add a short 'See also' navigation line pointing to any sibling skills (doc-writer, doc-sync panel, classifier) so the architect's place in the pipeline is discoverable rather than only implied.

Dimension	Reasoning	Score
Conciseness	The body is lean and task-dense — it assumes Claude knows the domain and avoids explaining what a TOC or SEO is, with only brief justificatory flourishes ("SEO debt is the silent corpus killer") that aid decisions without padding; every section (structural-shape table, YAML/JSON templates, validation rules) is actionable rather than explanatory.	3 / 3
Actionability	Provides concrete, copy-paste-ready YAML templates (new_page/moved_page/retired_page), a filled JSON output schema, a structural-shape table with real examples ("apm pack --format wheel"), and a specific command ("gh pr diff $PR"); per scoring_notes, this concrete instruction-only guidance is not penalized for lacking executable code.	3 / 3
Workflow Clarity	Steps 1–5 are explicitly sequenced, and Step 4 is a five-rule validation checklist with an explicit feedback loop ("If any fails, redesign") plus a promise_validation object in the output contract.	3 / 3
Progressive Disclosure	The body is well-sectioned into navigable headings (When to invoke, Inputs, Steps 1–5, Output contract, Anti-patterns) but is a monolithic ~140-line single file with no references, and the under-50-line simple-skill exemption does not apply.	2 / 3
	Total	11 / 12 Passed

Description

70%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, complete, and clearly niche-gated, but its trigger terms are dominated by internal pipeline jargon rather than natural user language. Rewording the trigger around user-facing intent would raise the weakest dimension.

Suggestions

Add natural user-facing trigger terms (e.g. 'docs TOC needs restructuring for a PR', 'new docs page needed', 'doc structure changes') alongside the classifier-verdict trigger so users can invoke it in their own words.

Spell out or gloss internal jargon ('TOC deltas', 'persona ramps', '3-promise narrative') with a plain-language parenthetical so the trigger is not opaque to readers outside the pipeline.

Lead with the user-observable condition ('when a PR requires new, moved, or merged documentation pages') before naming the internal classifier that detects it.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "Proposes TOC deltas (new pages, moves, merges) and emits new-page outline stubs" — rather than vague language; the imperative "Use this skill when…" matches the rubric's good-example voice, so no person-penalty applies.	3 / 3
Completeness	Explicitly answers both: what ("Proposes TOC deltas… emits new-page outline stubs… Holds the 3-promise narrative… as hard constraints") and when ("Use this skill when the docs-impact-classifier returns a structural verdict…"), with an explicit trigger clause.	3 / 3
Trigger Term Quality	The trigger leans on system-internal jargon ("docs-impact-classifier returns a structural verdict", "doc-sync panel", "3-promise narrative", "persona ramps") that a user would not naturally say, matching the technical-jargon anchor rather than natural keyword coverage.	1 / 3
Distinctiveness Conflict Risk	Gated on a specific classifier verdict ("when the docs-impact-classifier returns a structural verdict"), giving it a clear niche unlikely to trigger for unrelated skills.	3 / 3
	Total	10 / 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-architect/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.