# Apm Spec Guardian

Use this skill to run a four-panel adversarial advisory review on any pull request that...

- 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 apm-spec-guardian -g -a claude-code -y`
Codex: `npx skills add microsoft/apm --skill apm-spec-guardian -g -a codex -y`
Cursor: `npx skills add microsoft/apm --skill apm-spec-guardian -g -a cursor -y`
Gemini CLI: `npx skills add microsoft/apm --skill apm-spec-guardian -g -a gemini-cli -y`

## Description

Use this skill to run a four-panel adversarial advisory review on any pull request that touches the OpenAPM specification artifact (docs/src/content/docs/specs/openapm-*.md), its inline / sidecar JSON Schemas (docs/src/content/docs/specs/schemas/*.schema.json), or the conformance fixture seed (tests/fixtures/spec-conformance/**). The panel fans out to four spec-ecosystem reviewers (swagger-openapi-editor, oci-distribution-editor, pkgmgr-registry-contract-editor, w3c-tag-architect), each running in its own agent thread, and a spec-editor synthesizer that produces a fold-now / defer-v0.1.1 / defer-v0.2 / reject list plus a ship decision keyed off a 1..10 shocked_meter scale. The orchestrator is the sole writer to the PR: ONE consolidated comment, no verdict labels, no merge gating. The panel is advisory -- it surfaces findings, prioritizes folds, and renders a ship recommendation that the maintainer weighs.

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

# APM Spec Guardian -- Four-Panel Advisory Review for OpenAPM

This skill institutionalizes the two-round adversarial spec review
that produced OpenAPM v0.1 by hand. The panel is FAN-OUT +
SYNTHESIZER. Each panelist runs in its own agent thread (via the
`task` tool) and returns JSON matching
`assets/panelist-return-schema.json`. The orchestrator schema-validates
each return, hands all returns to the `spec-editor-synthesizer`
(also a task thread, returns JSON matching
`assets/synthesizer-return-schema.json`), runs the linter checklist
in `assets/linter-checklist.md`, then renders ONE comment from
`assets/comment-template.md`.

This skill is ADVISORY by design. It does not compute a binary
verdict, it does not apply verdict labels, and it does not gate
merge. The panel surfaces findings; the maintainer ships.

## Activation scope

This skill activates ONLY when the PR diff touches at least one of:

- `docs/src/content/docs/specs/openapm-*.md` (the normative spec
  artifact, current and future versions)
- `docs/src/content/docs/specs/schemas/*.schema.json` (sidecar JSON
  Schemas, if/when the inline Appendix-A schemas are extracted to
  files)
- `tests/fixtures/spec-conformance/**` (the conformance fixture seed)

Edits to any OTHER documentation page MUST NOT trigger this skill.
The maintainer's general `docs-sync` skill covers those.

## Architecture invariants

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