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

88%

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

81%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 tightly written, highly actionable orchestration skill with strong workflow sequencing, explicit validation checkpoints, and a real cost-ceiling feedback loop. Progressive disclosure is good and grounded in actual bundle files, though some detail lives in external .apm skill references rather than local files.

Dimension	Reasoning	Score
Conciseness	Dense, information-packed body with no padding of concepts Claude already knows — every section earns its place (invariants, roster table, topology, per-step instructions). Minor trims possible in the Step 7 governance prose, keeping it just below the lean 5 anchor.	4 / 5
Actionability	Provides concrete executable commands (`gh pr comment --edit-last`, `node scripts/governance/eligibility.cjs --repo ...`, `apm <verb> --help`, `grep -n <symbol> src/`) and exact JSON schemas to validate against. Not a 5 because several panelist tasks are described as 'spawn ONE task that loads the X skill' rather than showing the literal task invocation.	4 / 5
Workflow Clarity	Clear 7-step sequence with explicit validation checkpoints (schema-validate classifier JSON then abort on failure; cross-check refuted claims and re-run the writer; cost counter with ceiling abort), a redraft feedback loop bounded at N<=3, and a cost-accounting table — matching the anchor for explicit validation steps and error-recovery loops.	5 / 5
Progressive Disclosure	Well-organized overview body that delegates detail to real bundle files (assets/classifier-return-schema.json, assets/panelist-return-schema.json, assets/advisory-comment-template.md — all present) and to sibling .apm skills/agents via one-level-deep links. Not a 5 because several referenced targets are external skill/agent paths rather than co-located reference files, so navigation is partly out-of-bundle.	4 / 5
	Total	17 / 20 Passed

Description

95%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, third-person description with explicit 'Use whenever' triggers, concrete classified outcomes, and clear negative scope boundaries. It is comprehensive on trigger terms and distinctiveness while being only slightly process-heavy on specificity.

Dimension	Reasoning	Score
Specificity	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 the precise output artifact; not a 5 because the actions are somewhat process-oriented rather than enumerating distinct transformation operations.	4 / 5
Completeness	Explicitly answers both what ('Classifies impact... orchestrates a ... loop to produce a patch-ready advisory') and when ('Use this skill whenever a pull request is opened, reopened, or synchronized in microsoft/apm'), with concrete trigger phrases and explicit negative scope ('Does NOT review code quality...').	5 / 5
Trigger Term Quality	Comprehensive natural trigger coverage including 'pull request is opened, reopened, or synchronized', 'documentation corpus', 'PR title or body', 'silent drift between code and docs' — phrasings a user or workflow would naturally invoke; it explicitly activates even when the PR says nothing about docs.	5 / 5
Distinctiveness Conflict Risk	Clear niche — per-PR documentation drift detection for the microsoft/apm corpus — with explicit negative boundaries ('Does NOT review code quality, security, or test coverage. Does NOT auto-merge or auto-push') that minimize overlap with code-review or merge skills.	5 / 5
	Total	19 / 20 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 9 suspicious	Warning
referenced_paths_exist	Referenced path issues: 2 missing, 2 deeper-than-1-level	Warning

	Total	14 / 16 Passed

Repository: microsoft/apm
Path: .agents/skills/docs-sync/SKILL.md
Commit: b914b1b

Reviewed: 4 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.