Name: docs-sync
Rating: 68.8 (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

84%

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

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

A well-structured orchestration skill body with explicit validation checkpoints, a bounded alignment loop, and clear progressive disclosure to real bundle assets. It is slightly denser than strictly necessary and the actionability leans on task-spawning over copy-paste code.

Suggestions

Tighten the cost-accounting table and topology ASCII diagram, which partially restate information already conveyed in the step list, to reclaim tokens.

Consider adding a minimal copy-paste-ready code skeleton for the fan-out (e.g. an example task-tool invocation) to lift actionability from task-description to executable.

Verify the relative links to sibling skills and agents (../docs-impact-classifier/SKILL.md, ../../agents/*.agent.md) resolve, or move them to a single roster reference, to strengthen progressive disclosure navigation.

Dimension	Reasoning	Score
Conciseness	Dense and largely free of padding, assuming competence (e.g. 'Index-not-corpus reads', 'S7 deterministic tool bridge'); a few sections like the cost-accounting table and topology diagram restate info that could be trimmed, but overall efficient.	4 / 5
Actionability	Provides concrete executable commands ('apm <verb> --help', 'grep -n <symbol> src/', 'gh pr comment --edit-last'), schema file references, and specific branch/label values, though the fan-out is described as task spawning rather than copy-paste code.	4 / 5
Workflow Clarity	Seven clearly sequenced steps with explicit validation checkpoints (schema-validate classifier JSON in Step 1, validate panelist returns in Step 3, refuted-claim feedback loop in Step 4, CDO alignment loop with bounded redrafts in Step 5) and a cost-ceiling abort path.	5 / 5
Progressive Disclosure	Well-signaled one-level-deep references to real bundle files (assets/classifier-return-schema.json, assets/panelist-return-schema.json, assets/advisory-comment-template.md) and sibling skills/agents, with the body as an overview; minor gaps in that agent/skill links are not all verified as existing paths.	4 / 5
	Total	17 / 20 Passed

Description

85%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 strong, concrete description that covers what, when, and explicit boundaries, with a clear niche and low conflict risk. Minor room to broaden trigger synonyms and tighten the action list.

Dimension	Reasoning	Score
Specificity	Names the domain and lists several concrete actions ('Classifies impact as no-change, in-place edit, or structural change', 'orchestrates a CDO + doc-writer + python-architect + editorial-owner + growth-hacker loop to produce a patch-ready advisory'), with only minor coverage gaps around what the classification inputs are.	4 / 5
Completeness	Explicitly answers both what (classify, orchestrate panel, produce advisory) and when ('Use this skill whenever a pull request is opened, reopened, or synchronized') with concrete trigger phrasing and explicit negative boundaries ('Does NOT review code quality...').	5 / 5
Trigger Term Quality	Includes natural PR-event phrasing users would say ('pull request is opened, reopened, or synchronized') and the repo 'microsoft/apm', giving good keyword coverage, though it is missing a few common synonyms like 'PR'.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (per-PR documentation drift detection in microsoft/apm) with distinct triggers and explicit non-goals, making overlap with other skills minimal.	5 / 5
	Total	18 / 20 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: 71a877c

Reviewed: ~5 hours 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.