Name: docs-sync
Rating: 69.6 (1 reviews)
Author: microsoft

docs-sync

Use this skill whenever a pull request is opened, reopened, or synchronized in microsoft/apm to assess whether and how the documentation corpus must change to stay truthful with the proposed code change. Activate even when the PR title or body says nothing about docs -- the skill must run on every PR to detect silent drift between code and docs. Classifies impact as no-change, in-place edit (one to a few paragraphs), or structural change (new page or TOC reshape), then orchestrates a CDO + doc-writer + python-architect + editorial-owner + growth-hacker loop to produce a patch-ready advisory. Does NOT review code quality, security, or test coverage. Does NOT auto-merge or auto-push doc edits.

Quality

85%

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

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

A dense, operational orchestration skill with concrete file/command references, a well-sequenced multi-step workflow with validation and feedback loops, and clean progressive disclosure to verified bundle files. The only drag is deliberate-but-redundant restatement of the cost ceiling and single-writer interlock across several sections.

Suggestions

State the 15-call ceiling and single-writer interlock once in 'Architecture invariants' and reference them by name elsewhere (topology, cost accounting, anti-patterns) instead of restating the full constraint each time.

Collapse the cost-accounting table into the existing Step-level call counts so the per-step min/max figures live in one place rather than being implied by both the checklist and the table.

Dimension	Reasoning	Score
Conciseness	The body assumes Claude's competence (no basic-concept padding) and stays operational, but safety invariants like the 15-call ceiling and single-writer interlock are restated across invariants, topology, checklist, cost accounting, and anti-patterns, so it could be tightened.	2 / 3
Actionability	Guidance is concrete and executable: real schema files to validate against ('assets/classifier-return-schema.json', 'assets/panelist-return-schema.json'), specific commands ('apm <verb> --help', 'grep -n <symbol> src/'), exact branch name, label, comment header, and the 'safe-outputs.add-comment' tool -- all referencing verified bundle files.	3 / 3
Workflow Clarity	A clearly sequenced 7-step checklist with explicit validation checkpoints (schema validation with abort-on-failure, a dedicated Step 4 cross-check, refuted-claim re-runs) and a bounded CDO redraft feedback loop matches the anchor for clear sequences with error-recovery loops.	3 / 3
Progressive Disclosure	A well-organized overview (invariants, roster, topology, checklist, cost accounting, anti-patterns) points via one-level-deep markdown links to real bundle files in assets/ and sibling skills/agents, with content appropriately split and easy to navigate.	3 / 3
	Total	11 / 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.

A strong, third-person description with an explicit 'Use this skill whenever...' trigger, concrete capability list, and clear negative-scope boundaries. Its only weakness is trigger wording that uses webhook event jargon rather than natural user speech.

Suggestions

Soften the trigger to include natural phrasings a maintainer might say (e.g. 'docs drift', 'docs out of sync with code', 'keep docs truthful') alongside the webhook event terms.

Trim the persona roster enumeration in the description ('CDO + doc-writer + python-architect + editorial-owner + growth-hacker loop') to keep the what-it-does clause lean without losing the core classify-then-orchestrate action.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions -- 'assess whether and how the documentation corpus must change', 'Classifies impact as no-change, in-place edit...or structural change', and 'orchestrates a CDO + doc-writer + python-architect...loop to produce a patch-ready advisory' -- rather than vague language.	3 / 3
Completeness	An explicit 'Use this skill whenever a pull request is opened, reopened, or synchronized' clause answers 'when', and the classify-then-orchestrate loop answers 'what' clearly, satisfying the explicit-trigger requirement that would otherwise cap at 2.	3 / 3
Trigger Term Quality	Trigger coverage is relevant to the domain ('pull request is opened, reopened, or synchronized', 'docs', 'silent drift between code and docs') but leans on event-jargon like 'synchronized' rather than terms a user would naturally say, and common variations are thin.	2 / 3
Distinctiveness Conflict Risk	Niche is sharply bounded to per-PR documentation drift in microsoft/apm, and explicit 'Does NOT review code quality, security, or test coverage' / 'Does NOT auto-merge or auto-push' exclusions prevent overlap with adjacent skills.	3 / 3
	Total	11 / 12 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 9 suspicious	Warning

	Total	15 / 16 Passed

Repository: microsoft/apm
Path: .apm/skills/docs-sync/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.