daveebbelaar/bama

app-brief

One-page brief (docs/BRIEF.md) for a new macOS app, written before any code.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/daveebbelaar/bama --skill app-brief

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

App brief

Write docs/BRIEF.md in a folder named after the app (<parent>/<AppName>/docs/BRIEF.md; ask for the parent folder, default ~/Developer). Every later skill reads it. Keep it to one page.

1. Name and read what exists

Pick the name first: one UpperCamelCase word (Tasks, DailyLog), not the name of an app already in ~/Applications, and a bundle id com.<yourname>.<appname> in lowercase. The folder, the research, and the scaffold all use it.

If docs/research/ or docs/screens/INDEX.md exist, read them first. Skip every question they already answer.

If the user gives you a spec from BAMA's specs/ folder (a file or a link), it already holds the brief and the stories. Copy its Brief block to docs/BRIEF.md and its Stories block to docs/STORIES.md. Keep the rest of the spec as docs/SPEC.md, so later skills read its How it works and Gotchas. Ask only what the user wants to change, then call the Skill tool with new-mac-app.

2. Interview

Ask a few questions at a time. If the user asked you to decide everything, answer each question yourself from the research, write the choice in the brief, and note "decided by the agent" next to it.

  1. What do you do today, and which app or habit does it replace?
  2. What are the three things you do most often? These become the main pages.
  3. What data does it hold? Name the nouns: tasks, notes, recipes, invoices.
  4. Is there a reference app you like? Then the clone skill comes next.
  5. Where does it live: a window with a sidebar, a menu bar item, a

quick-capture panel with a global shortcut, or a mix?

  1. Does it need the internet? Default: no.
  2. Which three things are out of scope for version one?
  3. Should it look like a built-in Mac app, or have its own look? Note a

brand or accent color, and any app they name ("like Things"): the design-from-app skill rebuilds its look. No answer means native with the Mac's own accent color.

3. Cut scope

A personal app has one user. Remove what exists only for other users: accounts, sharing, teams, sync servers, billing, onboarding, analytics. If the user wants data on two Macs, note "later: iCloud sync".

Version one is one afternoon of agent time: one window, two to five main pages, one data model with two to four types. Smart lists that filter one model (Today, Upcoming, Someday) count as one page.

4. Write docs/BRIEF.md

markdown
# <AppName>

One sentence: what it is and who it is for.

## Replaces
<app or habit>

## Main jobs
1. ...
2. ...
3. ...

## Data
- <Type>: <fields>

## Shape
<sidebar window / menu bar extra / quick panel>, macOS 26 or later.
Local data. Works offline. No accounts.

## System hooks
<global shortcut, menu bar, Share menu, Shortcuts, CLI, or "none">

## Reference
<app name, or "none">

## Look
<native with an accent color (name it, or "system"), own parts, or "like <app>", and why>

## Not in version one
- ...

5. Hand off

Call the Skill tool with user-stories, or with new-mac-app if the user wants to see a window first.

Done when docs/BRIEF.md exists, fits on one page, and has every section.

from this repository

More skills

All skills
daveebbelaar
Community

mac-design

Design rules that make a SwiftUI app look and feel like a native Mac app on macOS 26 and later, from Apple's eight design principles to Liquid Glass, layout, toolbars, menus, search, keyboard, type, color, and dark mode. Use when building or reviewing any window, sidebar, toolbar, menu, panel, or settings screen, or when the user asks for a more native, Apple-like, or better designed app.

1h installs
1
GitHub stars
1.9K
Updated
Nov 5
daveebbelaar
Community

os-integrations

Deep macOS integrations for a native app, such as global hotkeys, menu bar items, floating panels, window control with Accessibility, screen capture and recording, clipboard, Shortcuts and Spotlight, URL schemes, login items, a CLI, and the permissions each one needs. Use when an app must reach outside its own window or control other apps.

1h installs
1
GitHub stars
1.9K
Updated
Nov 5
daveebbelaar
Community

agent-cli

Optional command line and MCP server for a macOS app, so Claude Code, Codex, and scripts can drive it (list, add, change, search, act) through the running app. Use when the user wants agents to work with their app or its data, asks for a CLI, an MCP server, or automation for the app, or says "Claude should be able to use my app".

1h installs
4
GitHub stars
1.9K
Updated
Nov 5
daveebbelaar
Community

app-icon

Liquid Glass macOS app icon made as an Icon Composer file (Icon/AppIcon.icon, JSON plus SVG layers), compiled with actool, and reviewed in every look with ictool. Use when the user wants an app icon, a better icon, or a Dock icon.

1h installs
4
GitHub stars
1.9K
Updated
Nov 5