Agent-Skills.md

Agent Skills: Verification Gate

Reusable verification gate for completed work before commit or merge. Use when implementation is done and Claude must prove the task works, verify the main user flow, route verification by platform, and return a PASS/FAIL/BLOCKED verdict with evidence. Web and mobile-web verification uses agent-browser. iOS and macOS verification uses xcodebuildmcp-cli.

UncategorizedID: iamhenry/ai-project-starter-kit/verification-gate
53

Install this agent skill to your local

pnpm dlx add-skill https://github.com/iamhenry/ai-project-starter-kit/tree/HEAD/.agents/skills/verification-gate

Skill Files

Browse the full folder contents for verification-gate.

Download Skill

Loading file tree…

.agents/skills/verification-gate/SKILL.md

Skill Metadata

Name
verification-gate
Description
Reusable verification gate for completed work before commit or merge. Use when implementation is done and Claude must prove the task works, verify the main user flow, route verification by platform, and return a PASS/FAIL/BLOCKED verdict with evidence. Web and mobile-web verification uses agent-browser. iOS and macOS verification uses xcodebuildmcp-cli.

Verification Gate

Use this skill after implementation and after code-quality-gate returns APPROVE_CODE, before commit or merge.

Mode Dispatch

  • The default, when mode is omitted, is the existing issue mode below. Any mode other than the explicit mode: isa request uses the existing issue-mode contract; do not auto-detect ISA inputs.
  • When the caller explicitly supplies mode: isa, use the alternate contract in references/isa-mode.md. Do not require, read, create, or infer {ISSUE_DIR}/plan.md for that invocation.
  • The two modes have separate inputs and output contracts. Do not mix issue artifacts into ISA verification or ISA inputs into issue verification.
  • Mechanical and Observable lanes below apply to issue mode only. ISA mode keeps declared leaf probes in references/isa-mode.md.

Keep the scope narrow:

  • Prove the intended task outcome works.
  • Choose the lightest platform route that creates confidence.
  • Return a clear verdict with evidence.

Do not use this skill for exploratory QA or bug hunting. Use dogfood for that.

Inputs

Collect the minimum context needed to verify the work:

ISSUE_DIR is the artifact directory created by gather-context for the current pipeline run.

  • plan.md Verification Target:
    • Platform: web|mobile-web|ios|macos|non-ui
    • Objective: single outcome to prove
    • Primary Flow: shortest realistic proof path
    • Regression Check: one adjacent behavior to protect, or None
    • Mechanical: named command(s) plus expected exit code or output
    • Observable: retained evidence path, or n/a for non-ui
    • Pass Criteria: concrete success condition
    • Blocked Conditions: known missing auth, data, environment, device, service, or tooling
  • changed behavior or files
  • target URL, command, or environment
  • auth, seed data, or other prerequisites
  • code-quality-gate result: APPROVE_CODE

If key prerequisites are missing and you cannot verify safely, return BLOCKED.

If Mechanical is missing from plan.md, return BLOCKED with unlock: revise the plan. Do not invent a command.

If the code-quality-gate result is missing, REVISE_CODE, or ASK_USER, return BLOCKED and do not run platform QA.

plan.md owns what to prove. This skill owns how to prove it by choosing the platform route and smallest proof path.

This skill must not edit application code, tests, or scorers. Re-run the named Mechanical command; do not rewrite it.

Platform Routes

Choose exactly one primary platform route:

  1. web
    • Use agent-browser for desktop browser UI flows, visible states, screenshots, and recordings.
  2. mobile-web
    • Use agent-browser with a mobile viewport/device profile for responsive browser UI flows and visible states.
  3. ios
    • Use xcodebuildmcp-cli for simulator/device build, launch, UI, and test verification.
  4. macos
    • Use xcodebuildmcp-cli for macOS app build, launch, UI, and test verification.
  5. non-ui
    • Use direct tests, build commands, API calls, CLI checks, data checks, or file assertions.

Prefer the smallest proof path that still demonstrates real user value.

Workflow

  1. Define the verification objective.

    • State the single main user outcome that must work.
    • Add one lightweight regression check when adjacent behavior could easily break.

  2. Map the proof flow.

    • Start from the first meaningful user or system action.
    • End at the success state the user cares about.
    • Avoid padding the flow with irrelevant steps.

  3. Execute verification.

    • If a declared environment prerequisite is unavailable, allow at most one narrow recovery attempt for that exact blocker. Do not redesign product or infrastructure inside verification. If recovery fails, return BLOCKED with the exact missing prerequisite and unlock condition.

    • Run Mechanical first. Execute the plan-named command(s) and quote raw output in the report. Do not paraphrase pass/fail. If Mechanical fails, return FAIL and skip Observable.

    • Then run Observable when it is not n/a. Use the platform route below. PASS requires both lanes when both are declared.

    • For web or mobile-web, use agent-browser instead of re-inventing browser steps.

    • Before browser commands, load agent-browser and follow its own CLI-served setup and usage guidance.

    • Follow the snapshot -> interact -> re-snapshot cadence.

    • Use named sessions.

    • Use screenshots for static proof points.

    • Use recordings only for multi-step interactions or async transitions that are hard to prove with screenshots alone.

    • For ios or macos, use xcodebuildmcp-cli.

    • First verify the CLI exists.

    • Use help-first discovery before commands: inspect available commands/options instead of relying on stale recipes.

    • Keep execution minimal: choose the smallest build, test, launch, simulator, or UI check that proves the Verification Target.

    • If xcodebuildmcp-cli is missing or the required project/device/runtime is unavailable, return BLOCKED with the missing prerequisite.

    • For non-ui, Mechanical is the proof path. Observable is n/a.

    • Prefer assertions tied to user-visible outcomes: command success, API response shape, file creation, persisted data, or other concrete results.

  4. Decide the verdict.

    • PASS: Mechanical passed, and Observable is proven when it is not n/a.
    • FAIL: Mechanical failed, the flow breaks, the result is wrong, cited files are missing, or the outcome cannot be proven.
    • BLOCKED: required auth, data, environment, or tooling is missing.

  5. Report the result.

    • Write {ISSUE_DIR}/verification/result.md first.
    • Run test -f on that file and every cited Observable path. Missing file = FAIL, not PASS.
    • Do not return PASS from chat alone.

Evidence Rules

  • Prove the whole flow, not just the final screen.
  • Capture only the evidence needed to support the verdict.
  • Never record secrets, tokens, private user data, or unnecessary personal information.
  • Raw snapshots, JSON, measurements, logs, base64, and duplicate media default to the OS temp area and are not durable unless the plan or leaf explicitly requires them. If ISSUE_DIR exists, store only retained evidence under {ISSUE_DIR}/verification/ with screenshots/ and videos/ subfolders.
  • Retain the minimum user-observable evidence needed by the claim: screenshots by default; a short video only when motion or lifecycle cannot be shown otherwise. Do not create evidence theater or retain artifacts that add no proof.
  • Always include artifact paths in the final report when evidence exists.
  • "No artifacts" is allowed only when Observable is n/a. If Observable names a path, that file must exist or the verdict is FAIL.

Screenshot Hygiene

  • Capture the smallest app-owned proof area that supports the verdict, not the full desktop.
  • For web and mobile-web, prefer the browser viewport.
  • For traditional macos apps, prefer the app window or the active sheet/modal bounds.
  • For menu bar apps, prefer the opened popover, panel, or menu bounds, and prefer deterministic QA hooks or launch flags over raw status-item clicks when available.
  • If bounded capture is unavailable, crop tightly, close unrelated windows first, and retake or delete artifacts that include private desktop content.
  • If only full-desktop capture is possible and it would expose private content, return BLOCKED instead of saving the artifact.

Artifact Cleanup

  • Treat runtime logs as temporary evidence unless the plan explicitly requires them.
  • Before returning PASS, remove or leave untracked noisy logs that may include local paths, hostnames, process IDs, or user/system details.
  • Preserve durable proof artifacts only: cropped screenshots, sanitized summaries, command pass/fail excerpts, or explicitly required files.
  • If logs must be kept, sanitize them first and mention why they are required.

Output

Use this exact structure:

## Verification Result

- Platform: `web|mobile-web|ios|macos|non-ui`
- Objective: [single outcome verified]
- Primary flow: [short description]
- Regression check: [short description or "None"]
- Mechanical: [command] → [exit code / quoted raw excerpt]
- Observable: [artifact path or `n/a`]
- Verdict: `PASS|FAIL|BLOCKED`

### Evidence

- [artifact path; `"No artifacts"` only when Observable is `n/a`]
- Report: `{ISSUE_DIR}/verification/result.md`

### Notes

- [key proof point, failure point, or blocker]

### Next Action

- [commit / fix issue / unblock environment]

Examples

  • web: Select model -> enter prompt -> submit -> generated images appear.
  • mobile-web: Open settings on mobile viewport -> verify new card, copy, and CTA render correctly.
  • ios: Build and launch app -> complete primary flow in simulator -> success state appears.
  • macos: Build and launch app -> complete primary flow -> success state appears.
  • non-ui: Run export command -> confirm output file exists and contains expected records.