# Docs Sync

Use this skill whenever a pull request is opened, reopened, or synchronized in...

- Repository: https://github.com/microsoft/apm (4171 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add microsoft/apm --skill docs-sync -g -a claude-code -y`
Codex: `npx skills add microsoft/apm --skill docs-sync -g -a codex -y`
Cursor: `npx skills add microsoft/apm --skill docs-sync -g -a cursor -y`
Gemini CLI: `npx skills add microsoft/apm --skill docs-sync -g -a gemini-cli -y`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# docs-sync -- per-PR documentation impact panel

The docs corpus drifts silently and constantly. This skill catches
drift at PR-open time, classifies its impact, and orchestrates a
persona panel to produce a patch-ready advisory comment.

The pattern is **A1 PANEL + B1 FAN-OUT/SYNTHESIZER + A8 ALIGNMENT
LOOP**. The classifier is the cost gate (~70% of PRs short-circuit
to no-change with ~1 LLM call). When the panel does fan out, every
agent reads a bounded context (~10 KB) -- never the full corpus.

This skill is ADVISORY. It does not gate merge, apply verdict
labels, or push to the contributor's fork. The orchestrator is the
sole writer to the PR: exactly one comment per run (idempotent
edit-in-place), plus optional label sweeps.

## Architecture invariants

- **Cost ceiling: 15 LLM calls per run.** Hard-wired. The orchestrator refuses to spawn beyond. Header prints `N/15` for observability.
- **Single-writer interlock.** Only the orchestrator writes. Panelist subagents return JSON; they MUST NOT call any `gh` write command, post comments, or touch PR state.
- **Idempotent comment.** Exactly one comment per run, with a stable header `## Docs sync advisory`. Re-runs edit-in-place using `gh pr comment --edit-last`.
- **No fork-write.** Companion docs PRs require Step 7's fresh responsible-human issue-scope checkpoint and open in the BASE repo; never pushed to the contributor's fork. Labels request advice, not implementation.
- **Index-not-corpus reads.** Every classifier and architect agent reads `.apm/docs-index.yml`, NOT the corpus itself. The corpus is sampled only by the localizer (which reads the specific candidate pages) and by per-page panelists (which read one page each).
- **S7 deterministic tool bridge.** The python-architect panelist MUST run real `apm --help`, `grep`, and `python -c` commands to verify doc claims, never assert from prose.

## Roster

The rest: https://github.com/microsoft/apm/blob/HEAD/.agents/skills/docs-sync/SKILL.md