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

Passed

No findings from the security scan

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.

The body is a well-engineered orchestration spec: actionable, with explicit validation checkpoints and clean one-level-deep references to real bundle files. The main weakness is conciseness — the topology diagram duplicates the execution checklist and several internal codes are used without being defined.

Suggestions

Either drop the ASCII 'Topology' diagram or trim the 'Execution checklist' so the two do not restate each other; keep one as the canonical sequence.

Define the internal pattern codes on first use (A1 PANEL, B1 FAN-OUT/SYNTHESIZER, A8 ALIGNMENT LOOP, A9 SUPERVISED EXECUTION, S7 tool bridge) in one short line, or link to where they are defined, so they are not opaque tokens.

Tighten the 'Operating modes' and 'Cost accounting' sections, which overlap with invariants already stated under 'Architecture invariants' and 'Anti-patterns'.

Dimension	Reasoning	Score
Conciseness	The body is dense and operational, but the ASCII 'Topology' diagram largely restates the 'Execution checklist', and internal codes (A1, B1, A8, A9, S7) are used without definition. Mostly efficient but could be tightened. Not 3 due to the redundancy and unexplained jargon; not 1 because there is no generic concept padding.	2 / 3
Actionability	Concrete and specific throughout: exact asset paths (assets/classifier-return-schema.json, assets/panelist-return-schema.json, assets/advisory-comment-template.md), real commands (gh pr comment --edit-last, apm <verb> --help, grep -n <symbol> src/), a concrete branch name (docs-sync/companion-<PR_NUMBER>), and a stable comment header. Instruction-only guidance is fully actionable.	3 / 3
Workflow Clarity	Steps 1–7 are clearly sequenced with explicit validation checkpoints: schema validation at Steps 1 and 3, refuted-claim re-run at Step 4, the 15-call cost ceiling interlock, and the bounded CDO revise loop (N<=3). Feedback loops are present for the batch/destructive companion-PR operation.	3 / 3
Progressive Disclosure	The body references three real bundle files in assets/ (classifier-return-schema.json, panelist-return-schema.json, advisory-comment-template.md), each one level deep and clearly signaled; schemas and the comment template are appropriately split out from the overview, and sections are well organized.	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.

The description is specific, complete, and clearly scoped, with explicit 'Use when…' triggers and useful negative boundaries. Its weakest point is trigger-term quality: the language is event- and jargon-heavy rather than phrased in terms a user would naturally say.

Suggestions

Add natural-language trigger phrases a user or maintainer would actually say (e.g. 'docs are out of sync with code', 'documentation drift', 'check docs impact of this PR') alongside the event-based trigger.

Move the internal persona roster ('CDO + doc-writer + python-architect + editorial-owner + growth-hacker loop') out of the description into the body; keep the description focused on user-facing capability and triggers.

Consider including the common variation 'docs sync' / 'documentation update' as an explicit keyword since the skill name itself is 'docs-sync'.

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'.	3 / 3
Completeness	Explicitly answers both: 'Use this skill whenever a pull request is opened, reopened, or synchronized…' (when) and the classify-then-orchestrate-panel behavior (what), plus explicit negative boundaries. Not 2 because the 'when' is stated, not merely implied.	3 / 3
Trigger Term Quality	Has relevant terms ('pull request', 'documentation', 'docs', 'drift') but the trigger is event-based and laden with internal jargon ('microsoft/apm', 'CDO + doc-writer + python-architect + editorial-owner + growth-hacker loop'), missing common user-spoken variations. Not 3 because a user would not naturally say these terms; not 1 because several relevant keywords are present.	2 / 3
Distinctiveness Conflict Risk	Tightly scoped to per-PR documentation drift in a named repo with distinct triggers ('detect silent drift between code and docs'); a clear niche unlikely to fire for unrelated 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: .agents/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.