Skip to main content
skill CX Codex

build-and-verify — Claude Code skill: build and check

build-and-verify — a Claude Code skill that builds SwiftUI macOS apps and checks page snapshots in light and dark appearance. The agent invokes it after UI changes, failed builds, or requests to run or inspect the app.

MIT 1,000 installs ★ 1,933 updated 2026-11-05

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add daveebbelaar/bama --skill build-and-verify -a claude-code
Open on GitHub

What build-and-verify does

The skill builds the app with ./build.sh, installs it, then captures each page and Settings tab in light and dark appearance. It checks the images and layout grid, then runs interaction tests; source code alone does not count as proof that a UI change is done.

Snapshots use a test database under /tmp, never the user's database. The app running screencapture needs Screen Recording permission; without it, sidebars and glass materials can appear blank. For apps that do not use the new-mac-app template, map the commands with existing-app.md first.

The skill asks the agent to open every PNG and inspect layout, dark-mode readability, and the match with the requested design. After the build and snapshots pass, it runs tools/selftest.sh, adds checks for new actions, and commits the change.

What it helps with

  • build a SwiftUI macOS app from the command line
  • inspect app pages in light and dark appearance
  • spot clipped text and blank areas in the UI
  • check the layout grid and newly added app actions

Example prompts for the agent

  • After the UI changes, build the app and inspect snapshots of every page.
  • The build failed; find the first error, fix it, and build again.
  • Run the app and check its interface in light and dark appearance.

How to install build-and-verify

1Skills CLI (Vercel)

npx skills add daveebbelaar/bama --skill build-and-verify -a claude-code

2Manually: put the files in place

~/.claude/skills/build-and-verify/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/build-and-verify/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about build-and-verify

How do I install build-and-verify in Claude Code?

Run npx skills add daveebbelaar/bama --skill build-and-verify -a claude-code. The skill is placed at ~/.claude/skills/build-and-verify/SKILL.md.

What does build-and-verify do?

It builds a SwiftUI macOS app, captures its pages in both appearances, checks the layout, and runs interaction tests.

What permission does build-and-verify need for snapshots?

The app running screencapture, such as Terminal or Claude, needs Screen Recording permission in macOS settings.

Source text

SKILL.md · MIT
---
name: build-and-verify
description: Build a SwiftUI macOS app from the command line, install it, and check light and dark window snapshots of every page before calling a change done. Use after any UI code change, when a build fails, or when the user asks to run, screenshot, or check the app.
allowed-tools: Bash(./build.sh*) Bash(swift *) Bash(tools/*) Bash(*/Contents/MacOS/*) Bash(open *) Read
---

# Build and verify

A change is done when four things are true:

1. `./build.sh` finishes with no errors.
2. You looked at the light and dark snapshots of every page you touched.
3. The snapshots match what the user story or reference screenshot asks for.
4. The grid checks pass (`layout-grid` skill).

App not made from the `new-mac-app` template (Xcode, XcodeGen, a menu bar
utility, Swift 5)? Map the commands below with
[existing-app.md](existing-app.md) first.

Do not report a UI change as done from the code alone. SwiftUI code that
compiles can still render an empty sidebar, clipped text, or unreadable dark
mode.

## 1. Build

```bash
./build.sh            # release build, installs ~/Applications/<AppName>.app
./build.sh --debug    # faster build while iterating
./build.sh --open     # also restarts the app so the user sees the new build
```

Read the errors, fix them, and build again. Fix the first error first: later
errors often come from it. If a new file is "not in scope" right after you
created it, run `swift package clean --scratch-path ~/Library/Developer/<AppName>/build`.

## 2. Snapshot

Run the installed binary directly with a test database and a folder for the
images. The app opens, walks through every sidebar page and every Settings
tab in light and dark mode, saves one PNG per page and mode, and quits.

```bash
tools/snap.sh
# SNAPSHOT /tmp/<AppName>-shots/all-light.png
# ...
# SNAPSHOT done /tmp/<AppName>-shots
```

`tools/snap.sh` deletes the old test store (with its `-wal` and `-shm`
files) and the saved window state first, then runs with sample data
(`APP_SEED=1`). Without that, seed data goes stale, and one crashed run
leaves a "reopen windows?" alert that hangs every later run.

Use `APP_SNAPSHOT_PAGES=today,inbox` to limit the pages. Add `settings` to
include the Settings tabs.

In every image, look for three bugs agents often miss: a focus ring or
selected text that nobody asked for, a scroll bar with nothing to scroll,
and an empty band under short content. The fixes are in `mac-design`,
"Windows open calm".

To see scroll bars as people with a mouse see them, add
`-AppleShowScrollBars Always` after the binary path. It changes only this
run.

Always use `APP_STORE` with a path in `/tmp`. Never take snapshots against the
user's real database in `~/Library/Application Support/<AppName>/`.

### Seed data

Empty pages only show empty states. The template's
`Sources/<AppName>/SeedData.swift` fills an empty test store when
`APP_SEED=1` is set. Grow it with the app: 10 to 20 items with long and
short titles, dates in the past and future, every priority and status, and
only what a person can create in the app.

### Screen Recording permission

Snapshots use `screencapture -l <window>`, which shows glass, sidebars, and
materials exactly as on screen. It needs Screen Recording permission for the
app that runs the command (Terminal, Ghostty, or Claude). If a snapshot line
ends with `(fallback: ...)`, the permission is missing and sidebars and glass
render blank. Ask the user to allow it in System Settings > Privacy &
Security > Screen & System Audio Recording, then restart the terminal.

### Missing snapshots

If every snapshot fails, or `screencapture` says "could not create image
from window", the display is probably asleep: an unattended Mac turns it
off. The template's snapshot mode wakes the display itself. For captures
from outside the app (like `window-shot.sh`), run `caffeinate -u -t 2` first.

If some states print "no window" while others work, another app hid yours
during the run. Computer use does this to apps it does not control, and so
does Hide Others. The template's snapshot mode un-hides the app and brings
the window forward before each capture. Run it again, and avoid using
computer use in another session at the same time.

## 3. Check the grid

```bash
tools/grid-lint.sh
swift tools/check-layout.swift /tmp/<AppName>-shots/*-layout.json
```

Both print PASS. On a FAIL, call the Skill tool with `layout-grid`: it has
the rules, the overlay, and a table of fixes.

## 4. Look

Open every PNG with the Read tool and check, in this order:

- Nothing is blank, clipped, or overlapping. Text fits. Sidebars show their items.
- Dark mode is readable. No fixed white or black surfaces.
- The page matches the story or the reference screenshot (layout, labels, order).
- The `mac-design` rules hold: glass only on controls, one accent,
  SF Symbols, system text styles, empty states that invite the first action.

Describe what you see in one or two sentences per page in your report, and
name the PNG paths so the user can open them.

## 5. Interaction checks

Snapshots show state, not behavior. Run `tools/selftest.sh` (exit 0 when
every check passes) and add a check for each new action. The
`test-mac-app` skill covers unit tests, the self-test, key events, the
menu check from outside, and a debug bridge.

### Inactive windows

Gray traffic lights mean the window was not key when it was captured:
sidebar text, selection, and toggles look dimmer than in use. A snapshot of
an inactive window does not count as reviewed. Run the snapshots again
while nobody else uses the screen, and do not "fix" dim text you only see
there.

### Debug output and private screens

A GUI app started with its output going to a file buffers `print`, and the
lines are lost when the process is killed. Write debug lines to stderr
(`FileHandle.standardError.write`) behind an environment flag.

Do not take full-screen captures to check your app: they show the user's
other windows. Capture your own window, or add a mode to the app that
renders the state you want to see (prefilled text, an open sheet).

## 6. Commit

When the build is clean and the snapshots look right, commit with a message
that says what the user can now do: "Add tasks from the quick-add panel",
not "Update views".

Done when the four conditions at the top hold and the change is committed.

© daveebbelaar · MIT · daveebbelaar/bama

Similar skills

All skills for Testing and QA →
cmux-debugging manaflow-ai cmux-debugging — a skill for adding debug logging, diagnosing UI and runtime issues in cmux. Use when working with terminal rendering, tab lists, drag-and-drop, or testing across macOS versions. CX Codex +1 5,000installs build-swiftui-interface memi-design build-swiftui-interface guides coding agents through SwiftUI interface design and verification on iOS and macOS. Enforces accessibility, state handling, and Xcode test checks. CX Codex +1 ★ 51repo stars build-macos-apps Lex Christopherson build-macos-apps is a Claude Code skill for building native macOS apps with SwiftUI and AppKit. It routes work on new apps, bugs, tests, performance, and releases to a matching workflow. CX Codex +1 ★ 1,988repo stars verify-pi-gui raylee-ai verify-pi-gui is a Claude Code skill that checks pi-gui conversations through the visible Electron app with a real provider. It covers message sending, streaming, thread changes, tools, drafts and restart behavior. CX Codex +1 ★ 364repo stars macos-design-guidelines platform-design-skills macos-design-guidelines supplies Apple Human Interface Guidelines for macOS apps in SwiftUI and AppKit. Useful when setting up menus, window controls, and keyboard shortcuts. CX Codex +1 4,600installs swiftui-design-skill wholiver swiftui-design-skill designs custom SwiftUI screens for iOS and macOS without generic AI clichés. Useful when drafting interface prototypes or picking a distinct visual direction. CX Codex +1 1,300installs

From the same set21

The whole set →
research This Claude Code skill researches a macOS app idea before development. It sends parallel subagents to compare products, user feedback, features, and macOS APIs. CX Codex +1 1,000installs improve-loop improve-loop — a Claude Code skill that works through a macOS app’s stories in docs/STORIES.md. It builds the app, checks screen snapshots against references, and commits completed work. CX Codex +1 1,000installs agent-cli agent-cli — a skill for Claude Code, Codex and Cursor that adds a command line and MCP server to a macOS app so agents can control it via a local socket. CX Codex +1 1,000installs performance performance — a skill for Claude Code that measures CPU, memory, and energy usage in macOS apps. It identifies causes of freezes and helps offload tasks from the main thread to the GPU. CX Codex +1 1,000installs improve-architecture The improve-architecture Claude Code skill reviews a macOS Swift codebase and plans refactors that preserve existing behavior. It activates before a major feature, at a milestone, or when bugs keep returning in one area. CX Codex +1 1,000installs app-brief The app-brief skill for Claude Code and Cursor generates a one-page docs/BRIEF.md file for a new macOS app before writing code. CX Codex +1 1,000installs design-from-app design-from-app — a Claude Code skill that rebuilds any app interface as a native SwiftUI design kit using reference screenshots. CX Codex +1 1,000installs os-integrations The os-integrations Claude Code skill maps macOS APIs to system-level features and their required permissions. It applies when adding global shortcuts, screen capture, or controls for other apps’ windows. CX Codex +1 1,000installs

Project sponsors

Companies that keep this analytics open