ax-audit
Audits agentic products for tool parity, authority, approval payloads, recovery, and trust using 27 rules and a ship verdict. Use when asked for an "AX audit", to review an agent approval flow, or whether an agent can operate the product. For human-facing API ergonomics use dx-audit; for ordinary UI use ui-design.
mblode · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add mblode/agent-skills --skill ax-auditAbout this skill
name: ax-audit description: Audits agentic products for tool parity, authority, approval payloads, recovery, and trust using 27 rules and a ship verdict. Use when asked for an "AX audit", to review an agent approval flow, or whether an agent can operate the product. For human-facing API ergonomics use dx-audit; for ordinary UI use ui-design.
AX Audit
Feature-level reviewer for apps where an agent acts for the user. One question: does it earn trust, and where does it break?
- IS: rules-based audit of agentic surfaces (chat, tool execution, config, dashboards) across architecture (
rules-arch/) and trust (rules-ax/), ending in a ship-readiness verdict plus an AX Relationship Summary. - IS NOT: traditional frontend UX (use
ui-designAudit mode); developer-facing API, CLI, or type ergonomics (usedx-audit); agent instruction files (useagents-md); what the product should do before it exists (useproduct-design).
No agentic features in scope? Stop. AX rules against forms and lists are noise.
Contents
- Audit workflow
- Two rule layers
- Tiers and verdict
- AX Relationship Summary
- Reference files
- Gotchas
- Audit self-check
- Related skills
Audit workflow
AX Audit progress:
- [ ] Step 1: Scope, via the diff against the PR base merge-base (PR mode) or explicit path (full sweep)
- [ ] Step 2: Detect agentic features per references/feature-playbooks.md
- [ ] Step 3: Run each detected feature's playbook in order, plus the diff-wide checks (PR mode only)
- [ ] Step 4: For each check, load the rule file and follow its detection recipe
- [ ] Step 5: Tier each finding per references/ship-readiness.md (rule override table wins)
- [ ] Step 6: Render verdict + findings + AX Relationship Summary per references/output-format.md
- [ ] Step 7: Run the audit self-check and report its evidence counts
PR-mode scope is the diff plus the tool definitions and orchestrator it touches. Findings in untouched files belong in a full sweep, not this verdict. Playbook annotations are a scan copy; the rule file is authoritative. parity-orphan-ui-action runs on every PR-mode audit and never in a full sweep, where there is no diff for it to read.
Rule greps name the most common identifiers, not every framework's spelling. When a grep misses in code that plainly does the thing (a gate, a stream, a tool result), check references/framework-signals.md for the stack's name for it before recording unknown.
Two rule layers
| Layer | Folder | Rules | Load when a playbook names |
|---|---|---|---|
| 1: Architecture | rules-arch/ | 12 | rules-arch/<category>-<slug>.md |
| 2: Experience | rules-ax/ | 15 | rules-ax/<category>-<slug>.md |
Categories: arch = parity, granularity, context, comm; ax = trust, control, context, comm. Shared prefixes are different rules: rules-arch/comm-no-approval-gate.md (no gate on the execution path) is not rules-ax/control-no-approval-gate.md (gate exists, stakes are wrong).
Run Layer 1 comm/parity and Layer 2 control/trust first. They hold the blockers. Category map: rules-arch/_sections.md, rules-ax/_sections.md.
| Priority | Layer | Category | Prefix | Rules |
|---|---|---|---|---|
| 1 | arch | Communication | comm- | 3 |
| 2 | arch | Parity | parity- | 4 |
| 3 | ax | Control | control- | 4 |
| 4 | ax | Trust | trust- | 4 |
| 5 | arch | Context | context- | 3 |
| 6 | ax | Communication | comm- | 4 |
| 7 | ax | Context | context- | 3 |
| 8 | arch | Granularity | granularity- | 2 |
Tiers and verdict
Three tiers. Full trigger lists and the generic surface bump live in references/ship-readiness.md.
Precedence: the rule's own surface-override table > the generic bump > defaultTier. Apply at most one adjustment.
Verdict: ✅ READY (0 blockers, ≤3 sprint) · ⚠️ READY WITH FOLLOW-UP (0 blockers, ≥4 sprint) · ❌ NOT READY (≥1 blocker) · 🚫 INCOMPLETE (self-check failed).
Blockers outrank an incomplete audit. With ≥1 release-blocker and a failed self-check, report ❌ NOT READY and note the self-check failure beneath it: the blockers are established findings and stay actionable, while 🚫 reads as "nothing was learned" and sends the reader away. Reserve 🚫 for an audit with no blockers whose coverage you cannot vouch for.
AX Relationship Summary
Render after findings when any agentic feature was detected. Findings serve engineers; this serves designers and PMs. Four fields: evolution stage (behavior, not a label), trust signal (high/moderate/low plus one-line reason), key gap (one actionable sentence), trust question (one question only research can answer).
Reference files
| File | Read when |
|---|---|
references/feature-playbooks.md | Steps 2-3: detection heuristics, per-feature ordered checks, diff-wide checks |
references/framework-signals.md | Step 4, when the code uses AI SDK, MCP, the Claude Agent SDK, or AG-UI: where the gate, the stream, the completion signal, and the structured result live in each, with the spec defaults the rules lean on |
references/ship-readiness.md | Step 5: tier triggers, precedence, verdict logic |
references/output-format.md | Step 6: findings JSON schema, summary schema, terminal rendering |
references/agent-native-principles.md | A Layer 1 finding needs grounding the rule file does not carry |
references/ax-evolution-curve.md | Writing the AX Relationship Summary: stage, action depth, costume vs intelligence |
references/invisible-interface.md | Grounding for structured tool output, approval payload, access scope, unprompted action; also the arguments that stay in keyGap |
references/evaluation-scenarios.md | When changing this skill. Never loads during a user audit |
rules-arch/_sections.md | Layer 1 categories, default tiers, co-firing pairs |
| `ru |