Skip to main content
skill CX Codex

performance · daveebbelaar — Claude Code skill: what it does, how to install

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.

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

What performance does

This skill automates profiling for macOS applications to reduce interface latency and fix freezes. The workflow follows a cycle: reproducing the issue, measuring metrics in a release build, identifying the problematic code, and verifying the fix.

It utilizes standard utilities like sample, xctrace, footprint, and leaks. Always measure release builds, as Debug Swift runs significantly slower. Since .trace files may contain environment tokens, never commit or share them.

What it helps with

  • identify interface freezes
  • reduce CPU and memory usage
  • eliminate animation stutter
  • monitor app energy consumption

Example prompts for the agent

  • performance: measure response time when opening the window
  • performance: check why the app consumes high energy

How to install performance

1Skills CLI (Vercel)

npx skills add daveebbelaar/bama --skill performance -a claude-code

2Manually: put the files in place

~/.claude/skills/performance/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/performance/

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

Questions about performance

How to install performance in Claude Code?

Run npx skills add daveebbelaar/bama --skill performance -a claude-code in your terminal.

What does the performance skill do?

It measures hangs, CPU, memory, and energy usage to help optimize macOS apps by offloading tasks to the GPU.

What is required to use this skill?

A macOS environment and Apple command-line tools like xctrace and sample are required.

Source text

SKILL.md · MIT
---
name: performance
description: Make a macOS app fast by measuring hangs, stutter, CPU, memory, and energy, then moving work off the main thread and onto the GPU. Use when the app freezes, a shortcut feels slow, dragging stutters, the fan spins, memory grows, or the user asks to optimize or profile.
---

# Performance

Fast means two numbers: the first frame after a key press shows in under
100 ms, and nothing on the main thread blocks for more than 50 ms. Every
change in this skill starts and ends with a **measurement**, so you know it
helped. Symptom-by-symptom fixes are in [recipes.md](recipes.md). For
video, audio, camera, Metal, or large image pipelines, also read
[gpu-media.md](gpu-media.md).

## The loop

```text
reproduce -> measure (release build) -> find the line -> fix -> measure again -> commit with the numbers
```

1. **Reproduce.** Write the exact steps, or add a probe command to the
   debug bridge (`test-mac-app` skill) that runs the slow action and logs
   the time of each step.
2. **Measure the release build.** Debug Swift is 3 to 10 times slower and
   points at the wrong code.
3. **Find the line.** Pick the tool for the symptom:

   | Symptom | Tool |
   | --- | --- |
   | App freezes, spinning pointer | `sample <App> 5`, then read the main thread stack |
   | Slow action | Time Profiler: `xcrun xctrace record --template 'Time Profiler' --attach <App> --time-limit 10s` |
   | Short freezes while typing or dragging | `--template 'Hangs'` |
   | Stutter while moving or animating | `--template 'Animation Hitches'` |
   | Memory grows | `footprint <App>`, `leaks <App>`, `--template 'Allocations'` |
   | Fan, battery | `--template 'Energy Log'`, look for timers and polling |

   Read traces as text, not in the Instruments GUI: see "Measuring" in
   [recipes.md](recipes.md). Delete every `.trace` after reading. A trace
   stores the app's full environment, and an app opened from an agent's
   shell inherits that shell's tokens. Never commit or share one.

4. **Fix** with the matching recipe.
5. **Measure again** with the same steps. Put before and after in the
   commit message: "Picker opens in 40 ms, was 600 ms".

## The rules that fix most problems

- **Main thread does UI only.** File, network, database, image decoding,
  Accessibility calls, and audio go elsewhere. A main-thread call that waits
  on another process (CoreAudio, AX) can freeze the app for minutes.
- **Show first, work after.** Put the window or panel on screen in the same
  frame as the key press, then load. Never make the UI wait for the work.
- **Let the GPU composite.** Large images go in a `CALayer` once. Pointer
  movement changes only small layers. Never redraw a full-screen picture per
  mouse event.
- **Decode at display size.** ImageIO thumbnails, cached in `NSCache`.
- **Do not animate what must be fast.** Search results and switchers
  update in place.
- **No polling without a reason.** Timers get a tolerance and stop when
  nothing on screen needs them.

## Apple silicon notes

- Core Animation, Core Image (one shared `CIContext`), Vision, and
  AVFoundation already run on the GPU or the Neural Engine. Hand them the
  work instead of looping over pixels in Swift.
- Write Metal (`MTKView`, compute shaders) only when a measurement shows
  Core Animation or Core Image is too slow. Most apps never need it.
- Unified memory means a `CGImage` from ScreenCaptureKit passes to a layer
  without a copy. Keep it as a `CGImage` or `IOSurface`. Converting to
  `NSImage` and back costs copies.

Done when the slow action has a measured before and after, the after meets
the two numbers at the top, and the commit message names both.

© daveebbelaar · MIT · daveebbelaar/bama

Similar skills

All skills for Agent setup: memory, context, orchestration →

performance by other authors comes first.

performance millionco This skill measures React runtime performance for one repeatable interaction and ties browser delays to component renders. CX Codex +1 314installs performance plugin87 This Claude Code skill guides UI performance work against Core Web Vitals. It activates for slow interactions, animation jank, layout shifts, and loading problems. CX Codex +1 562installs performance rshankras performance diagnoses slow apps, hangs, and memory leaks using Instruments; spots unnecessary SwiftUI re-renders and view identity issues. CX Codex +1 212installs performance OrchestKit This skill helps diagnose slow web pages, React renders, backend requests, and LLM inference across a performance review. CX Codex +1 233installs performance cognitedata performance is a Claude Code skill that finds and fixes performance issues in Flows apps. It activates for requests about slow pages, re-renders, CDF queries, bundles, or memory leaks. CX Codex +1 1,900installs native-app-performance steipete CLI skill for analyzing native app performance via xctrace and Time Profiler. Records execution traces, extracts samples, symbolicates stack frames, and identifies bottlenecks without opening Instruments. CX Codex +1 251installs swiftui-performance dpearson2699 swiftui-performance — a skill for Claude Code, Cursor, Codex and other agents that takes a reproducible SwiftUI symptom through to a measured fix. CX Codex +1 5,000installs instruments-profiling steipete The instruments-profiling skill guides macOS and iOS profiling with Instruments and xctrace, from trace capture to stack export. Use it when a native app has a slow path. CX Codex +1 242installs agent-performance-engineer Tony363 agent-performance-engineer is a Claude Code skill for finding bottlenecks and tuning applications, databases, and infrastructure. It activates for profiling, load testing, and performance work. CX Codex +1 556installs performance-profiling MengTo Guides performance profiling for Apple apps using Instruments and MetricKit. It directs the AI agent to pinpoint hangs and slow launch times. CX Codex +1 1,700installs performance-optimization gamedev-skills The performance-optimization Claude Code skill measures game frame time and tracks down low FPS or stutter in Godot, Unity, Unreal, and Roblox. It activates for profiling requests and frame-rate problems. CX Codex +1 14,200installs

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 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 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