skills.rest
microsoft
microsoftOFFICIAL
Explore all skills by this author →
Website𝕏@OpenAtMicrosoftGitHub

apm-spec-guardian

Runs a four-panel adversarial advisory review on pull requests touching the OpenAPM specification.

3.7k|344|Updated Sep 18, 2025
Search Tags:#JSON Schema#linter#specification review#advisory panel#Multi-Agent#Pull request#openapm
One-click install
npx skills add https://github.com/microsoft/apm --skill apm-spec-guardian
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: apm-spec-guardian
Source: https://github.com/microsoft/apm/tree/main/.apm/skills/apm-spec-guardian
Command: npx skills add https://github.com/microsoft/apm --skill apm-spec-guardian

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes assets (resource) components.

What problem does it solve?

Reviewing changes to a normative specification artifact requires multiple expert perspectives, but coordinating that review manually is slow and inconsistent. This Skill automates a structured multi-persona review of any pull request that modifies the OpenAPM spec, its JSON Schemas, or its conformance fixtures, producing one consolidated advisory comment for the maintainer.

Core Features & Use Cases

  • Four-panel fan-out review: Spawns four spec-ecosystem reviewer agents (OpenAPI editor, OCI distribution editor, package-manager registry editor, W3C TAG architect) in parallel, each returning schema-validated JSON findings.
  • Synthesizer with ship decision: Aggregates panel findings into fold-now, defer-v0.1.1, defer-v0.2, and reject lists plus a ship_decision driven by a shocked_meter floor and blocker veto.
  • Mechanical linter: Runs 11 checks covering ASCII-only enforcement, forbidden vendor-foundation tokens, schema validity, anchor uniqueness, and normative-statement count consistency.
  • Use Case: A contributor opens a PR editing docs/src/content/docs/specs/openapm-v0.1.md. The skill classifies the diff, fans out the four panelists, synthesizes their findings, lints the artifact, and posts exactly one advisory comment with a ship recommendation.

Quick Start

Apply the spec-review label to a pull request that modifies the OpenAPM specification artifact and let the panel post its consolidated advisory comment.

Frequently Asked Questions about apm-spec-guardian

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run a multi-persona review on a specification pull request?▼

Apply the spec-review label to a PR that touches the OpenAPM spec artifact, its JSON Schemas, or conformance fixtures. The skill fans out four panelist agents in parallel, synthesizes their findings, and posts one consolidated advisory comment.

What files trigger the apm-spec-guardian review panel?▼

The skill activates only when the PR diff touches docs/src/content/docs/specs/openapm-*.md, sidecar schemas under docs/src/content/docs/specs/schemas/*.schema.json, or fixtures under tests/fixtures/spec-conformance/. Other documentation edits do not trigger it.

Does the spec review panel block merging a pull request?▼

No, the panel is strictly advisory. It emits a ship_decision (fold_and_ship, needs_revision, or next_brief) as prose for the maintainer, applies no verdict labels, and never gates merge status.

How does the ship decision get computed from panel findings?▼

If any panelist returns a blocking finding, the decision must be next_brief. Otherwise, if the average shocked_meter across the four panels is below 7.0, the decision is needs_revision; only at 7.0 or above may it be fold_and_ship.

What does the spec linter check before the comment is posted?▼

The linter runs 11 mechanical checks including ASCII-only bytes, forbidden vendor-foundation tokens, JSON Schema validity, fixture parsing, req-anchor uniqueness, normative-statement count consistency across three sites, and Markdown anchor resolution.

When is the full four-panel review skipped for small spec edits?▼

Editorial-only diffs (under 50 added and 50 removed lines, no schema changes, no fixture additions, no anchor changes) skip the panel fan-out entirely and run only the linter, rendering a lightweight comment.

Related Skills

Explore More Software Engineering Skills→
deneb-cygnus-devdeneb-cygnus-dev

draft-pr

Generate a conventional commit title and markdown PR description from a git branch diff.

Community
Intermediate
yabafreyabafre
2

aped-iterate

Classify post-ship product deltas and route them to downstream APED skills.

Community
Intermediate
olioskarolioskar

review

Run structured code reviews on pull requests and branches with severity-ranked findings.

Community
Advanced
rdmptvrdmptv

moai-workflow-project

Initialize MoAI Menu projects and migrate legacy configurations to a unified format.

Community
Advanced