CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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.

68

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

73%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 an exceptionally well-sequenced orchestration policy: topology diagram, per-mode wave routing, schema validation with bounded retry loops, a mandatory mechanical linter, and a single-writer output contract, with every referenced bundle asset real and one level deep. Its weaknesses are structural repetition (each core rule restated 3-5 times) and two unresolved references (inconsistent persona paths, an undefined safe-outputs interface), which hold conciseness and actionability below the top anchors.

Suggestions

State each core rule (advisory regime, single-writer interlock, ASCII-only, no-vendor-foundation ban) once in 'Architecture invariants' and cross-reference it from the wave sections, output contract, and gotchas instead of restating it verbatim 3-5 times.

Resolve the persona-path inconsistency: the roster table links ../../../.apm/agents/spec-*.agent.md while Wave 3 instructs subagents to load ../../agents/spec-<slug>.agent.md -- pick one canonical relative path.

Define or link the safe-outputs interface (add-comment max: 1, remove-labels) so the Wave 6 sweep and single-emission interlock are executable without external repo knowledge.

DimensionReasoningScore

Conciseness

The body explains no concepts Claude already knows and is dense with skill-specific policy, but core rules are restated many times: 'advisory, not gate regime', the single-writer interlock, ASCII-only, and the no-vendor-foundation ban each appear 3-5 times across 'Architecture invariants', the wave sections, the 'Output contract', and 'Gotchas' (e.g. 'NEVER render the words Verdict, APPROVE, REJECT' appears in both Wave 6 and the output contract, and again inside assets/comment-template.md). Mostly efficient but could be tightened to one canonical statement plus cross-references, which matches anchor 3 ('mostly efficient but includes some unnecessary explanation or could be tightened') better than anchor 4's 'minor instances'.

3 / 5

Actionability

Wave 0 gives exact thresholds ('diff added < 50 lines AND removed < 50 lines', 'no anchor of the form `<a id="req-`', the literal marker 'apm-spec-guardian: new-version'), Waves 3-4 enumerate prompt fields and verbatim decision rules ('If sum(panelist.new_blocking_findings) > 0 ... MUST be next_brief', 'shocked_meter_avg < 7.0 -> needs_revision'), and Waves 5-6 map to real, verified bundle assets. Minor gaps keep it below anchor 5: the roster table cites personas at '../../../.apm/agents/spec-*.agent.md' while Wave 3 instructs '../../agents/spec-<slug>.agent.md' (two different paths for the same files), and the 'safe-outputs.remove-labels' interface invoked in Wave 6 is not defined anywhere in the bundle.

4 / 5

Workflow Clarity

The topology diagram plus numbered waves (0, 3, 4, 5, 6) with explicit per-mode skip rules give a fully clear sequence, and every stage has a validation checkpoint with a feedback loop: 'S4 schema-validate per return ... on malformed: re-spawn that panelist (max 2 attempts; then placeholder)', re-spawn the synthesizer 'once with the violation cited', a mandatory 11-check linter before render (verified: assets/linter-checklist.md contains exactly 11 checks), and a loop budget with exhaustion semantics ('the maintainer should ESCALATE'). This matches anchor 5's 'explicit validation steps; feedback loops for error recovery; checklists'.

5 / 5

Progressive Disclosure

All four referenced assets (panelist-return-schema.json, synthesizer-return-schema.json, linter-checklist.md, comment-template.md) exist and are one level deep, and the bulky material is correctly split out of SKILL.md, which itself stays an orchestration overview. It is not anchor 5 because the persona agent files live outside the bundle at two inconsistent paths ('../../../.apm/agents/...' in the roster vs '../../agents/...' in Wave 3), making navigation to them ambiguous, and some inlined wave/gotcha prose could live in assets -- 'good structure; most content is appropriately placed; minor organization gaps' (anchor 4).

4 / 5

Total

16

/

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 description: it explicitly states what the skill does (four-panel adversarial advisory review with fan-out, synthesis, and a single-writer consolidated comment) and when to use it (PRs touching the three named spec paths), with concrete trigger conditions, third-person imperative voice, and near-zero conflict risk. The only soft spot is trigger-term breadth -- internal jargon like 'shocked_meter' and 'fold-now / defer-v0.1.1' dominates over the phrases a user would naturally say when invoking it.

Suggestions

Add one or two natural-language trigger phrases a maintainer would actually say (e.g. 'spec review' or 'review the OpenAPM spec PR') alongside the path globs to broaden trigger-term coverage.

DimensionReasoningScore

Specificity

It lists multiple concrete actions covering the whole pipeline: 'run a four-panel adversarial advisory review on any pull request that touches the OpenAPM specification artifact', 'fans out to four spec-ecosystem reviewers (swagger-openapi-editor, oci-distribution-editor, pkgmgr-registry-contract-editor, w3c-tag-architect)', a 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', and 'ONE consolidated comment'. This matches anchor 5 ('multiple specific concrete actions; comprehensive coverage') rather than anchor 4, since no meaningful action of the skill is left unstated.

5 / 5

Completeness

Both halves are explicit: the 'what' ('run a four-panel adversarial advisory review ... fans out to four spec-ecosystem reviewers ... a spec-editor synthesizer that produces a fold-now / defer / reject list plus a ship decision') and the 'when' ('on any pull request that touches the OpenAPM specification artifact (docs/src/content/docs/specs/openapm-*.md), its inline / sidecar JSON Schemas (...), or the conformance fixture seed (...)'), which matches anchor 5's pattern of answering what AND when with concrete trigger phrases, and exceeds anchor 4's 'when could be more explicit'.

5 / 5

Trigger Term Quality

Natural domain terms are present ('pull request', 'OpenAPM specification', 'spec', 'JSON Schemas', 'conformance fixture seed') plus concrete path globs ('openapm-*.md', '*.schema.json', 'tests/fixtures/spec-conformance/**') that function like file extensions. A few natural phrasings a maintainer might actually say ('spec review', 'review the spec PR') are missing, so it sits just below anchor 5's 'comprehensive coverage of natural terms including synonyms' and fits anchor 4 ('good keyword coverage; a few natural terms missing').

4 / 5

Distinctiveness Conflict Risk

Activation is scoped to exact repository paths (the spec artifact, its schemas, and the fixture seed), a niche no generic review skill would claim, and it even draws the boundary against sibling skills ('The maintainer's general docs-sync skill covers those' non-spec edits). This is anchor 5's 'clear niche with distinct triggers; minimal conflict risk', not anchor 4, which still admits overlap with closely related skills.

5 / 5

Total

19

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

relative_links

Relative link issues: 5 suspicious

Warning

Total

15

/

16

Passed

Repository

microsoft/apm

Path

.agents/skills/apm-spec-guardian/SKILL.md

Reviewed

Table of Contents

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.