Agent skill

proof

Use proof to capture test runs as shareable, replayable evidence artifacts. Invoke this skill whenever the user wants to preserve or share proof that tests passed — not just run tests, but document and share the results. Works from any language: standalone binary, TypeScript, Python, or Go SDKs. Key use cases: attaching terminal output to a PR so reviewers can replay the test session instead of trusting a screenshot; generating a markdown proof report to embed in PR descriptions or tickets; recording a browser test run as a self-contained HTML video to share with a PM or QA team; recording an iOS Simulator or Android emulator screen while XCUITest or Espresso tests run, with automatic tap indicator overlays; exporting terminal recordings as MP4 video for embedding inline in Linear or Jira comments; or creating an audit trail that ties passing tests to a specific git commit. Trigger on phrases like "attach evidence to PR", "save test output as artifact", "replayable test recording", "proof report", "record my test run", "share test results", "visual proof tests pass", "terminal recording of tests", "record iOS simulator", "record Android emulator", "capture mobile tests", "export as video", "embed in Linear", "embed in Jira", or whenever someone wants reviewers or stakeholders to see test execution without re-running it themselves. Also trigger when the user mentions proof, @automaze/proof, or automaze-proof directly.

View SKILL.md on GitHub Repository
Stars 38
Forks 1

Install this agent skill to your Project

npx add-skill https://github.com/automazeio/proof/tree/main/skills/proof

SKILL.md

proof

Capture evidence that code works. Terminal replays, browser videos, structured reports.

When to use this skill

  • User asks to record or capture test execution
  • User wants visual evidence of a command running
  • User needs to generate a proof report
  • User wants to attach test recordings to PRs or share them
  • User wants to record an iOS Simulator or Android emulator while running mobile UI tests
  • User mentions "proof", "evidence", or "capture" in the context of testing

Install

proof ships as a standalone binary. No Node.js required.

bash
# macOS / Linux
curl -fsSL https://automaze.io/install/proof | sh

# Homebrew
brew install automazeio/tap/proof

# npm (if you have Node.js)
npm install -g @automaze/proof

# Verify
proof --version

Choose your interface

Interface Install Best for
CLI binary curl / brew Shell scripts, CI, any language
TypeScript SDK npm install @automaze/proof Node.js / Bun projects
Python SDK pip install automaze-proof Python projects, pytest
Go SDK go get github.com/automazeio/proof-go Go projects

All SDKs are thin wrappers around the same CLI binary.

CLI (works everywhere)

The CLI outputs JSON to stdout, making it ideal for agent consumption and scripting.

Terminal capture

bash
# Default: produces .cast + .html interactive player
proof capture \
  --app <app-name> \
  --command "<shell command>" \
  --mode terminal \
  --label <label> \
  --dir <output-dir> \
  --run <run-name> \
  --description "<what this captures>"

# Video export: produces .mp4 for embedding in Linear / Jira comments
proof capture \
  --app <app-name> \
  --command "<shell command>" \
  --mode terminal \
  --format video \
  --label <label> \
  --dir <output-dir>

Browser capture

bash
proof capture \
  --app <app-name> \
  --test-file <path/to/test.spec.ts> \
  --mode browser \
  --label <label> \
  --dir <output-dir>

Simulator capture (iOS)

Records the iOS Simulator screen while running XCUITest (or any command). Requires Xcode and at least one simulator runtime installed locally.

bash
proof capture \
  --app <app-name> \
  --mode simulator \
  --platform ios \
  --device-name "iPhone 17 Pro" \
  --command "xcodebuild test \
    -project MyApp.xcodeproj \
    -scheme MyApp \
    -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
    -parallel-testing-enabled NO \
    -disable-concurrent-destination-testing" \
  --label ui-tests \
  --dir <output-dir>

For pixel-accurate tap indicators, add ProofTapLogger.swift to the XCUITest target and replace element.tap() with element.proofTap(). Proof reads the tap log after the test and overlays red dot + ripple rings at the correct positions.

Simulator capture (Android)

Records the Android emulator screen while running Espresso or any command. Requires Android SDK and at least one AVD created locally.

bash
proof capture \
  --app <app-name> \
  --mode simulator \
  --platform android \
  --device-name "Pixel_3a" \
  --command "./gradlew connectedAndroidTest" \
  --label ui-tests \
  --dir <output-dir>

For tap indicators, write a JSON tap log from your test script:

bash
cat > /tmp/proof-android-taps.json << 'EOF'
[
  { "element": "Login", "x": 540, "y": 1200, "offsetMs": 1000 },
  { "element": "Submit", "x": 540, "y": 1800, "offsetMs": 3500 }
]
EOF

Proof reads $PROOF_TAP_LOG (default /tmp/proof-android-taps.json) after recording and overlays indicators.

Generate report

bash
proof report --app <app-name> --dir <output-dir> --run <run-name> --format md
proof report --app <app-name> --dir <output-dir> --run <run-name> --format html
proof report --app <app-name> --dir <output-dir> --run <run-name> --format md,html,archive

JSON stdin mode (multi-capture)

bash
echo '{
  "action": "capture",
  "appName": "my-app",
  "proofDir": "./evidence",
  "run": "full-suite",
  "captures": [
    { "command": "npm test", "mode": "terminal", "label": "unit" },
    { "command": "npm run lint", "mode": "terminal", "label": "lint" }
  ]
}' | proof --json

CLI output format

json
{
  "action": "capture",
  "appName": "my-app",
  "run": "deploy-v2",
  "recordings": [
    {
      "path": "/absolute/path/to/unit-143012.html",
      "mode": "terminal",
      "duration": 1200,
      "label": "unit"
    }
  ]
}

TypeScript SDK

typescript
import { Proof } from "@automaze/proof";

const proof = new Proof({
  appName: "my-app",
  proofDir: "./evidence",
  run: "deploy-v2",
});

await proof.capture({
  command: "npm test",
  mode: "terminal",
  label: "unit-tests",
  description: "Unit test suite",
});

await proof.report();
await proof.report({ format: "html" });
await proof.report({ format: "archive" });

See TypeScript SDK reference for full API.

Python SDK

bash
pip install automaze-proof
python
from proof import Proof

p = Proof(app_name="my-app", proof_dir="./evidence", run="deploy-v2")

rec = p.capture(command="pytest tests/ -v", mode="terminal", label="tests")
print(rec.path)      # /abs/path/tests-143012.html
print(rec.duration)  # 2400

p.report()
p.report(format="html")

pytest fixture

python
# conftest.py
import pytest
from proof import Proof

@pytest.fixture(scope="session", autouse=True)
def proof_session(tmp_path_factory):
    p = Proof(app_name="my-app", proof_dir="./evidence")
    yield p
    p.report()

See Python SDK reference for full API.

Go SDK

bash
go get github.com/automazeio/proof-go
go
import "github.com/automazeio/proof-go/proof"

p, err := proof.New(proof.Config{AppName: "my-app", ProofDir: "./evidence"})
rec, err := p.Capture(proof.CaptureOptions{
    Command: "go test ./...",
    Mode:    "terminal",
    Label:   "tests",
})
fmt.Println(rec.Path, rec.Duration)

p.Report(proof.ReportOptions{})

The Go SDK auto-downloads the binary on first use if not on PATH.

See Go SDK reference for full API.

Report formats

Format File Use case
md report.md Default. Markdown summary, paste into PRs
html report.html Visual HTML report with embedded media
archive archive.html Single self-contained HTML. Fully portable

Output structure

<proofDir>/<appName>/<YYYYMMDD>/<run>/
  label-HHMMSS.cast        # asciicast v2 recording
  label-HHMMSS.html        # self-contained terminal player
  label-HHMMSS.mp4         # terminal video export (format=video only)
  label-HHMMSS.webm        # browser video (if browser mode)
  proof.json                # manifest with all entries
  report.md                 # generated report

Common agent workflows

Record test execution after making changes

bash
proof capture --app my-app --command "npm test" --mode terminal \
  --label tests --dir ./evidence --run "$(date +%H%M)" \
  --description "Tests after implementing feature X"

Record multiple test suites

bash
echo '{
  "action": "capture",
  "appName": "my-app",
  "proofDir": "./evidence",
  "run": "full-suite",
  "captures": [
    { "command": "npm run test:unit", "mode": "terminal", "label": "unit" },
    { "command": "npm run test:integration", "mode": "terminal", "label": "integration" },
    { "command": "npm run lint", "mode": "terminal", "label": "lint" }
  ]
}' | proof --json

Generate report for a PR

bash
proof report --app my-app --dir ./evidence --run full-suite --format md

Key constraints

  • Terminal mode requires --command
  • Browser mode requires --test-file
  • Simulator mode requires --command and --platform
  • --format video only applies to terminal mode; requires Playwright Chromium (npx playwright install chromium) and ffmpeg
  • --app is always required
  • CLI always outputs JSON to stdout, errors go to stderr
  • Report generation requires at least one capture in the run
  • Simulator mode requires the simulator/emulator to be installed locally -- proof does not download or provision them
  • For iOS xcodebuild tests, always pass -parallel-testing-enabled NO -disable-concurrent-destination-testing or the recording will capture an idle screen (xcodebuild clones the simulator by default)

References

  • CLI guide
  • TypeScript SDK
  • Python SDK
  • Go SDK

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

automazeio/ccpm

ccpm

CCPM - spec-driven project management: PRD → Epic → GitHub Issues → parallel agents → shipped code. Use this skill for anything in the software delivery lifecycle: writing a PRD ('write a PRD for X', 'let's plan X', 'scope this out'), parsing a PRD into an epic, decomposing an epic into tasks, syncing to GitHub ('sync the X epic', 'push tasks to github'), starting work on an issue ('start working on issue N', 'let's work on issue N'), analyzing parallel work streams, running standups ('standup', 'run the standup'), checking status ('what's next', 'what's blocked', 'what are we working on'), closing issues, or merging an epic. Use ccpm any time the user is talking about shipping a feature, managing work, or tracking progress — even if they don't say 'ccpm' or 'PRD'. Do NOT use for: debugging code, writing tests, reviewing PRs, or raw GitHub issue/PR operations with no delivery context.

7,950 804
Explore
mattpocock/skills

obsidian-vault

Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.

111,310 9,758
Explore
mattpocock/skills

setup-pre-commit

Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.

111,310 9,758
Explore
mattpocock/skills

scaffold-exercises

Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.

111,310 9,758
Explore
mattpocock/skills

git-guardrails-claude-code

Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.

111,310 9,758
Explore
mattpocock/skills

edit-article

Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.

111,310 9,758
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results