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

86%

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

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 well-engineered orchestration skill body: clearly sequenced multi-step workflow with strong validation and feedback loops, and clean one-level-deep references to sub-skills, agents, and verified assets. Weakest point is conciseness — unexplained internal pattern labels (A1/B1/A8/S7/A9) and some redundancy across the roster, topology, and step sections.

Suggestions

Define or link the internal taxonomy labels (A1 PANEL, B1 FAN-OUT/SYNTHESIZER, A8 ALIGNMENT LOOP, S7 tool bridge, A9 SUPERVISED EXECUTION) on first use so a reader need not infer them.

Consolidate the agent-role information so the Roster table, Topology diagram, and Steps do not each re-describe the same panelists; reference the roster from the steps instead.

Show the concrete task-tool invocation pattern once (e.g. a sample `Task` call loading docs-impact-classifier with the PR number argument) to lift actionability from mostly-executable to copy-paste ready.

Dimension	Reasoning	Score
Conciseness	Dense and lean with no generic-concept padding ('The docs corpus drifts silently...'), but unexplained internal taxonomy labels (A1/B1/A8/S7/A9) and mild redundancy between the Roster table, Topology diagram, and Steps could be trimmed.	4 / 5
Actionability	Provides concrete commands (`gh pr comment --edit-last`, `apm <verb> --help`, `grep -n <symbol> src/`), schema paths, branch-name patterns, and JSON return shapes, but the task-spawning mechanics ('spawn ONE task that loads the X skill') are described abstractly without invocation syntax.	4 / 5
Workflow Clarity	Steps 1–7 are explicitly sequenced with validation checkpoints (schema validation on every return, refuted-claim writer re-run, cost-ceiling interlock) and bounded feedback loops (CDO revise N<=3), and batch fan-out operations carry validation so the destructive/batch cap does not apply.	5 / 5
Progressive Disclosure	The orchestrator body is an overview that points one level deep via markdown links to sub-skills and agent definitions, and references three verified bundle files (classifier-return-schema.json, panelist-return-schema.json, advisory-comment-template.md), with content appropriately split and easy to navigate.	5 / 5
	Total	18 / 20 Passed

Description

92%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 that clearly states both the trigger (every PR open/reopen/sync in microsoft/apm) and the concrete behavior (classify, orchestrate a persona panel, emit an advisory), with explicit out-of-scope boundaries. Only minor weakness is reliance on internal persona-role jargon over user-natural synonyms in the trigger phrasing.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Classifies impact as no-change, in-place edit..., or structural change' and 'orchestrates a CDO + doc-writer + python-architect + editorial-owner + growth-hacker loop to produce a patch-ready advisory' — giving comprehensive coverage of what the skill does.	5 / 5
Completeness	Explicitly answers both 'what' (assess/classify/orchestrate panel/produce advisory) and 'when' ('whenever a pull request is opened, reopened, or synchronized... the skill must run on every PR') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Covers natural domain triggers ('whenever a pull request is opened, reopened, or synchronized', 'silent drift between code and docs') but leans on internal persona jargon and omits common synonyms like 'docs out of date'; good but not exhaustive.	4 / 5
Distinctiveness Conflict Risk	Scoped narrowly to microsoft/apm PR docs-impact with explicit negative boundaries ('Does NOT review code quality, security, or test coverage. Does NOT auto-merge or auto-push'), giving a clear niche with minimal conflict risk.	5 / 5
	Total	19 / 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: .agents/skills/docs-sync/SKILL.md
Commit: 71a877c

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