Skip to main content
skill CX Codex

improve-loop — Claude Code skill: features and installation

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.

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 improve-loop -a claude-code
Open on GitHub

What improve-loop does

The skill selects the first todo story in the current milestone whose dependencies are done, then moves it through planning, coding, a build, snapshot checks, and a commit. It runs ./build.sh and sets APP_SEED=1 to populate pages with sample content.

It compares each affected screen with its reference, checking behavior, wording, and layout. After making changes, it rebuilds and checks again, with a limit of three comparison rounds per story. If the result still differs, the story goes back to todo with a note about what blocks it. New pages are added to SidebarItem so snapshot mode can visit them.

At the milestone boundary, the skill records completed stories in docs/STORIES.md and reports finished and blocked work. It then runs ./build.sh --open. The project needs docs/STORIES.md and ./build.sh; the workflow also follows the swift-swiftui, mac-design, and build-and-verify skills.

What it helps with

  • work through milestone stories in dependency order
  • build a macOS app and capture the screens changed by a story
  • compare screenshots with references and address visible differences
  • commit completed stories and report blockers

Example prompts for the agent

  • Work through the stories in docs/STORIES.md until milestone M2 is complete, then stop.
  • Take the app through the story queue and compare changed screens with their reference snapshots.
  • Run the story backlog unattended and report anything blocked.

How to install improve-loop

1Skills CLI (Vercel)

npx skills add daveebbelaar/bama --skill improve-loop -a claude-code

2Manually: put the files in place

~/.claude/skills/improve-loop/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/improve-loop/

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

Questions about improve-loop

How do I install improve-loop in Claude Code?

Run npx skills add daveebbelaar/bama --skill improve-loop -a claude-code. The skill file is at ~/.claude/skills/improve-loop/SKILL.md.

What does improve-loop do?

It implements stories from docs/STORIES.md one at a time, builds the macOS app, checks screenshots against references, fixes differences, and commits the work.

How many screenshot comparison rounds does improve-loop allow?

It allows up to three rounds for each story. If differences remain, the story returns to todo with a note describing the blocker.

Source text

SKILL.md · MIT
---
name: improve-loop
description: Autonomous loop that works through docs/STORIES.md one story at a time for a macOS app, building, snapshotting, comparing against reference screenshots, fixing, and committing, until a milestone is done. Use when the user says "keep going", "work through the backlog", "make it match the reference", or wants an unattended improvement loop.
argument-hint: "[milestone, e.g. M1]"
---

# Improve loop

One pass through the loop takes one story from `todo` to `done`:

```text
pick story -> plan -> code -> ./build.sh -> snapshot -> compare -> fix -> commit -> update STORIES.md
```

Stop after the milestone the user named, or after the current milestone if
they named none. Then report.

## 1. Pick

Open `docs/STORIES.md`. Take the first `todo` story in the current
milestone whose dependencies are `done`. Set it to `doing`.

## 2. Plan

If the story adds a screen, an action, or words and has no `UX:` block
yet, call the Skill tool with `ux-design` first.

Write two to five lines in your head or in the commit body: which files
change, which model fields are new, which menu command and shortcut it adds,
which snapshot page shows it. If the story needs a new SwiftData field, give
it a default value so existing databases keep loading.

## 3. Code

Follow the `swift-swiftui` and `mac-design` skills, the story's `UX:`
block, and `design/DESIGN-SYSTEM.md` if the app has one. System hooks follow
`os-integrations`. Keep each view file under about 300 lines.
Put new pages in the `SidebarItem` enum so snapshot mode visits them.

## 4. Build and snapshot

Follow the `build-and-verify` skill. If the story has logic, add a test
or a self-test step (`test-mac-app` skill). Use seed data (`APP_SEED=1`) so pages
show real content.

## 5. Compare

Open your snapshot and the story's reference screenshot side by side with
the Read tool. Write down the differences that matter, in this order:

1. Missing or wrong behavior from the acceptance criteria.
2. Words and flow: names, surface, and states that differ from the `UX:`
   block or `docs/GLOSSARY.md`.
3. Layout: wrong column, wrong order, missing element, and every FAIL from
   the grid checks.
4. Hierarchy: what is biggest, boldest, first.
5. Spacing and alignment.
6. Color and details.

The goal is the same structure and behavior, built from Apple's own controls.
It is not a pixel copy. When the reference uses a web-style custom control
and macOS has a native one (a toolbar, a sidebar, a context menu, a date
picker), use the native one.

No reference screenshot (no app was cloned)? Compare against the story's
acceptance lines and the `mac-design` rules instead.

Snapshot only the pages a story touches (`APP_SNAPSHOT_PAGES`), and the
full set at the end of each milestone.

Fix, rebuild, and compare again. Three rounds per story at most. If it still
does not match, set the story to `todo` again with a note that says what is
blocking, and move on.

## 6. Commit and record

```bash
git add -A
git commit -m "Complete tasks with Command-Return"
```

Set the story to `done` in `docs/STORIES.md` and commit that with the code.
One story per commit, so any story can be reverted on its own. M1 may
land as one commit when its stories share one skeleton (model, pages,
list, persistence); from M2 on, one story per commit.

## 7. Report

At the end of the loop, report to the user:

- Stories done, with one line each and the snapshot paths that show them.
- Stories blocked, and why.
- Anything the user should try by hand (shortcuts, drag and drop).
- The next story in line.

Then `./build.sh --open` so the user can try the new build.

## Milestone check-in

When the last story of a milestone is `done`, call the Skill tool with
`improve-architecture` before you start the next milestone. Unattended, do
its top recommendation only if it is `Strong`, and leave the rest in the
review file for the user.

When a story fixes a bug, add an entry to `docs/FIXLOG.md`: symptom,
cause, fix, and a last line `Rule: <what to always or never do>`. The fix
log outlives squashed history, and the check-in reads it.

## Running it unattended

The loop works with no one watching, because every step checks itself:
the build, the snapshots, the acceptance criteria. To let it run longer,
start it with a clear limit ("finish M2, then stop"), make sure the tree is
committed before you start, and never let it touch the user's real database.
Each story is a separate commit, so the user can review the history in the
morning and revert anything they do not like.

Done when every story in the milestone is `done` or named in the report as
blocked with a reason, each done story has its own commit, and the user
has the report.

© daveebbelaar · MIT · daveebbelaar/bama

Similar skills

SKILL.md skills catalog →

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 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 build-and-verify 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. 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