apm-spec-guardian

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.

Quality

79%

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

Fix and improve this skill with Tessl

tessl review fix ./.apm/skills/apm-spec-guardian/SKILL.md

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.

The body is a well-structured, highly actionable orchestration spec with clear sequenced waves, validation checkpoints, and well-signaled bundle references. Its main weakness is repetition of the same invariants across multiple sections, which inflates the token budget.

Suggestions

State each invariant (advisory regime, no-vendor-foundation, single-writer) once in 'Architecture invariants' and reference it from the waves rather than restating verbatim.

Move the full per-wave prompt templates into a referenced asset file, keeping the body as an overview of the wave sequence.

Collapse the 'Output contract', 'Gotchas', and invariant restatements where they duplicate the topology and wave sections.

Dimension	Reasoning	Score
Conciseness	Mostly efficient but several invariants are restated multiple times (the advisory regime, the no-vendor-foundation rule, and the single-writer interlock each appear across the architecture invariants, individual waves, and the output contract), which could be tightened.	3 / 5
Actionability	Provides fully concrete, executable orchestration guidance: exact wave structure, exact per-task prompt contents, exact gh safe-outputs calls, schema validation steps, and a mechanical linter checklist.	5 / 5
Workflow Clarity	Sequences a multi-step process (Wave 0 through 6) with explicit validation checkpoints (schema-validate each panelist return, re-spawn on failure, mandatory linter before render), feedback loops, loop budgets, and a gotchas section covering failure modes.	5 / 5
Progressive Disclosure	Content is appropriately split into real, one-level-deep, clearly-signaled bundle files under assets/ (panelist-return-schema.json, synthesizer-return-schema.json, linter-checklist.md, comment-template.md) and per-persona agent files; the body still carries substantial inline detail that could live in references.	4 / 5
	Total	17 / 20 Passed

Description

77%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.

The description is highly specific, complete, and well-scoped to a distinct niche, but its trigger terms are technical and unlikely to match what a user naturally says. Rewording around plain-language PR/spec-review triggers would lift the weakest dimension.

Suggestions

Add natural trigger phrasing a user would actually say, e.g. 'Use when reviewing a PR that changes the OpenAPM spec, its JSON Schemas, or conformance fixtures'.

Soften or gloss the jargon ('adversarial advisory review', 'shocked_meter') so a non-expert contributor can recognize when the skill applies.

Consider naming the artifact type early in plain terms ('spec review') before the path globs.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions with comprehensive coverage: four-panel fan-out to named reviewers, a synthesizer producing fold-now/defer-v0.1.1/defer-v0.2/reject lists, a 1..10 shocked_meter, and single-writer consolidated comment.	5 / 5
Completeness	Clearly and explicitly answers both what (runs a four-panel advisory review with a synthesizer and single-writer comment) and when (any PR touching the named openapm spec, schema, or fixture paths).	5 / 5
Trigger Term Quality	It is jargon-heavy ('adversarial advisory review', 'conformance fixture seed', 'shocked_meter') and lacks the natural phrases a user would actually say when they need this skill, though it does lead with an explicit 'Use this skill to run...'.	2 / 5
Distinctiveness Conflict Risk	Carves a clear niche scoped to the OpenAPM spec artifact and explicitly excludes other docs (deferring those to the maintainer's docs-sync skill), giving minimal conflict risk.	5 / 5
	Total	17 / 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: 5 suspicious	Warning

	Total	15 / 16 Passed

Repository: microsoft/apm
Path: .apm/skills/apm-spec-guardian/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.