New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Swiftui Debugging

by st0012 in st0012/cctop

A skill your agent uses when debugging SwiftUI issues in this macOS app — views not updating, layout problems, unnecessary re-renders, state ownership bugs, Preview crashes, or NSHostingView/NSPanel…

MITAuto-check passedMobile

Install Swiftui Debugging

skills CLI
$ npx skills add st0012/cctop --skill swiftui-debugging -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install st0012/cctop swiftui-debugging --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/st0012/cctop.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/swiftui-debugging .claude/skills/swiftui-debugging && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
swiftui-debugging
GitHub stars
154
Token cost
~2k tokens
SKILL.md length
725 words
Files
1
Skills in repo
7
Repo updated
First seen
Licence
MIT

At a glance

A skill your agent uses when debugging SwiftUI issues in this macOS app — views not updating, layout problems, unnecessary re-renders, state ownership bugs, Preview crashes, or NSHostingView/NSPanel…

  • Works in 3 steps: Log at the data source (model/manager)… → Check if the view reads external state… → Use Self._printChanges() at the top of…
  • Debugging SwiftUI issues in this macOS app — views not updating
  • SKILL.md covers Overview, Logging in macOS Apps, View Not Updating and State Ownership Bugs, plus 5 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Swiftui Debugging is an agent skill from st0012/cctop. Use when debugging SwiftUI issues in this macOS app — views not updating, layout problems, unnecessary re-renders, state ownership bugs, Preview crashes, or NSHostingView/NSPanel quirks. Covers both general SwiftUI debugging and macOS-specific patterns.

Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Mobile, covering iOS development and Debugging. It works with SwiftUI and macOS. The repository describes itself as: A keyboard-first menubar app to monitor and jump between AI coding sessions — minimum setup required. The licence is MIT.

When your agent uses it

  • Debugging SwiftUI issues in this macOS app — views not updating
  • Layout problems
  • Unnecessary re-renders
  • State ownership bugs

Example prompts

  • “/swiftui-debugging”

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. Log at the data source (model/manager) and at the view's body — confirm data changed but body wasn't called
  2. Check if the view reads external state (singletons, managers) not passed through its struct inputs
  3. Use Self._printChanges() at the top of body to see what SwiftUI thinks triggered (or didn't trigger) a re-evaluation

What it can do on your machine

Read from SKILL.md and the folder at commit 4ee2258. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are swift).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Swiftui Debugging loads about 2k tokens when it runs. Until then it costs about 68 tokens; SKILL.md has 725 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~68
When it runs · the whole SKILL.md, loaded when a task matches
~2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from st0012/cctop at commit 4ee2258, republished under its MIT licence (© st0012). 725 words, ~1,964 tokens.

Download SKILL.mdSave it as .claude/skills/swiftui-debugging/SKILL.md (or your agent's skills folder).
name
swiftui-debugging
description
Use when debugging SwiftUI issues in this macOS app — views not updating, layout problems, unnecessary re-renders, state ownership bugs, Preview crashes, or NSHostingView/NSPanel quirks. Covers both general SwiftUI debugging and macOS-specific patterns.

SwiftUI Debugging

Overview

Systematic approaches for debugging SwiftUI issues in macOS apps. Covers view updates, state ownership, performance, layout, and macOS-specific quirks with NSHostingView and NSPanel.

Logging in macOS Apps

print() and NSLog() are invisible when launching macOS apps from CLI or Finder (menubar-only apps have no console). Always use file-based logging:

swift
func debugLog(_ message: String) {
    let entry = "\(Date()) \(message)\n"
    let url = URL(fileURLWithPath: "/tmp/debug.log")
    if let handle = try? FileHandle(forWritingTo: url) {
        handle.seekToEndOfFile()
        handle.write(entry.data(using: .utf8)!)
        handle.closeFile()
    } else {
        try? entry.write(to: url, atomically: true, encoding: .utf8)
    }
}

Remove all debug logging before committing. Use grep -r "debugLog" --include="*.swift" to verify.

View Not Updating

Symptom

View shows stale data after a confirmed state change. Common with hostingView.rootView = NewView(...) not propagating to children, or theme/color changes not reflecting.

Root Cause: SwiftUI Diffing

SwiftUI skips re-evaluating a child view's body if the child's struct inputs haven't changed — even if the child reads from a singleton or computed property that did change.

Parent: rootView = MyView(counts: same)
  → SwiftUI: "counts didn't change, skip child body"
  → Child: never re-reads StatusColors.working
  → Result: stale colors
Diagnosis
  1. Log at the data source (model/manager) and at the view's body — confirm data changed but body wasn't called
  2. Check if the view reads external state (singletons, managers) not passed through its struct inputs
  3. Use Self._printChanges() at the top of body to see what SwiftUI thinks triggered (or didn't trigger) a re-evaluation
Fixes
Root CauseFix
Child reads external state not in its inputsPass a changing value and add .id(value) to force recreation
@State destroyed by .id() changesExtract into @StateObject owned by parent above the .id() boundary
NSColor(name:) dynamic colors cachedUse .id() to force re-resolution
@Published changed but view doesn't updateVerify view uses @ObservedObject, not a plain property
.id() Force-Recreation
swift
struct NotchStatusView: View {
    let counts: StatusCounts
    var themeId: String = ""  // changes when theme changes

    var body: some View {
        HStack { ... }
            .id(themeId)  // forces ALL children to recreate
    }
}

Tradeoff: .id() destroys the entire subtree including @State.

State Extraction (surviving .id())
swift
// Move @State into @StateObject owned above the .id() boundary
class OverlayController: ObservableObject {
    @Published var active: Overlay?
}

struct ParentView: View {
    @StateObject private var controller = OverlayController()  // survives
    var body: some View {
        ChildView(controller: controller)
            .id(themeId)  // safe — controller lives here
    }
}

State Ownership Bugs

@State vs @StateObject vs @ObservedObject
WrapperOwned byLifetimeUse when
@StateThe viewDies with view identity (.id())Simple value types internal to one view
@StateObjectThe view that creates itSurvives re-renders, dies with viewYou create the object and own its lifetime
@ObservedObjectSomeone elseYou don't control itPassed in from parent, not owned here
Common Bug: @ObservedObject with inline init
swift
// BUG: creates new instance every re-render, losing state
struct MyView: View {
    @ObservedObject var model = MyModel()  // wrong — recreated each time
}

// FIX: use @StateObject for owned objects
struct MyView: View {
    @StateObject var model = MyModel()  // correct — created once
}

Unnecessary Re-renders

Diagnosis

Add Self._printChanges() at the top of body to see what SwiftUI thinks changed:

swift
var body: some View {
    let _ = Self._printChanges()  // prints: "MyView: @self, _count changed."
    ...
}
Common Causes
  • Struct not Equatable — SwiftUI can't diff, re-renders every time. Add Equatable conformance.
  • Closure properties — closures aren't equatable; every parent render creates a new closure. Move closures to methods or use EquatableView.
  • Overly broad @Published — publishing a large object when only one field changed. Break into granular publishers or use @Observable (macOS 14+).

Layout Debugging

Visual debugging
swift
// Highlight view bounds
.border(Color.red)
.background(Color.blue.opacity(0.2))

// Check what size SwiftUI gives a view
.overlay(GeometryReader { geo in
    Text("\(Int(geo.size.width))×\(Int(geo.size.height))")
        .font(.caption2).foregroundColor(.red)
})
Common Layout Issues
  • View collapses to zero — missing .frame() or parent doesn't propose a size. Check with background(Color.red).
  • Text truncation — fixedSize() lets text exceed proposed size, or use lineLimit(nil).
  • GeometryReader takes all space — it's greedy. Wrap in an explicit .frame() or use it only for reading, not sizing.
Show full SKILL.md (283 more words)Show less

Preview Debugging

Preview crashes silently
  • Check the diagnostic in Xcode's canvas (click the error icon)
  • Previews run in a separate process — crashes in init() or computed properties won't show a stack trace
  • Use mock data that avoids file system, network, or singleton access
Preview works but app doesn't (or vice versa)
  • Previews use a different bundle — Bundle.main returns different values
  • Previews may not have the same entitlements (e.g., no Automation permission)
  • @AppStorage reads from a different UserDefaults suite in previews

macOS-Specific: NSHostingView and NSPanel

NSHostingView rootView replacement

Setting hostingView.rootView = NewView(...) does NOT recreate the view tree — SwiftUI diffs the old and new struct. If inputs are identical, children skip body evaluation. This is the most common source of "view not updating" bugs in macOS apps using NSHostingView.

NSPanel quirks
  • needsDisplay = true on NSHostingView does nothing — SwiftUI manages its own display cycle
  • orderOut(nil) hides but doesn't destroy the hosting view; state persists
  • For clickable panels (e.g., notch pill), use NSPanel with styleMask: [.nonactivatingPanel] and override canBecomeKey to avoid stealing focus
@MainActor cascade

Making a type @MainActor (e.g., to access ThemeManager.shared) cascades to everything that uses it. Plan for this — it often requires @MainActor on models, renderers, controllers, and test classes. Add it top-down rather than chasing compiler errors bottom-up.

Quick Reference

ProblemFirst step
View shows stale dataSelf._printChanges() — is body even called?
View never re-rendersCheck property wrappers — @ObservedObject vs @StateObject
State resets unexpectedlyLook for .id() changes destroying @State
Can't see print outputUse file-based logging (/tmp/debug.log)
Layout wrong.border(Color.red) on suspect views
Preview crashesCheck for singleton/file access in init
NSHostingView children staleInputs unchanged → use .id() to force recreation
@MainActor errors everywhereAdd top-down from the root type, not bottom-up

© st0012, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/swiftui-debugging of st0012/cctop.

Open the folder on GitHubat commit 4ee2258

Compare with similar skills

Swiftui Debugging next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Swiftui Debugging compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Swiftui Debugging this skillst0012/cctop154—~2kAutomated safety check: PassMIT
Apple Crash Log .NET Symbolicationdotnet/skills5.6k1 repos~2.4kAutomated safety check: PassMIT
Capture Usage4claude Screenshotsf-is-h/Usage4Claude400—~3kAutomated safety check: PassMIT
macOS DevelopmentKartikLabhshetwar/better-shot2.4k2 repos~735Automated safety check: PassCustom licence
Playback Webview Debuggingsozercan/kaset2.4k—~480Automated safety check: PassMIT
Code ReviewRobertoMachorro/Moped115—~2.1kAutomated safety check: PassGPL-3.0

Similar skills

  • Apple Crash Log .NET Symbolication

    dotnet/skills

    Official

    Resolves .NET runtime frames in Apple .ips crash logs to function names, source files and line numbers using dSYM symbols, atos and the Microsoft symbol server.

    5.6k GitHub starsUsed in 1 repo~2.4k tokens
    MobileAuto-check passed

  • Capture Usage4claude Screenshots

    f-is-h/Usage4Claude

    Produce every Usage4Claude interface image used by the READMEs and docs.

    400 GitHub stars~3k tokensUpdated 8 days ago
    MobileAuto-check passed

  • macOS Development

    KartikLabhshetwar/better-shot

    Comprehensive macOS development guidance including Swift 6+, SwiftUI, SwiftData, architecture patterns, AppKit bridging, and macOS 26 Tahoe APIs.

    2.4k GitHub starsUsed in 2 repos~735 tokens
    MobileAuto-check passed

  • Playback Webview Debugging

    sozercan/kaset

    A skill your agent uses when playback, auth recovery, queue sync, or hidden WebView state diverges from native Swift state and you need to debug the DRM playback WebView, bridge events, or…

    2.4k GitHub stars~480 tokensUpdated 3 days ago
    MobileAuto-check passed

  • Code Review

    RobertoMachorro/Moped

    Review guidance for Moped, a sandboxed macOS SwiftUI text editor with a homegrown TextKit 1 editor core in the local MopedEditor package.

    115 GitHub stars~2.1k tokensUpdated 2 days ago
    MobileAuto-check passed

  • Protect Knowledge Boundary

    ShiinaLabs/wifi-lens

    Invoke only when the user explicitly requests a WiFi Lens knowledge-boundary audit or the active task names that audit as a required deliverable.

    118 GitHub stars~1.6k tokensUpdated yesterday
    MobileAuto-check passed

More from st0012/cctop

  • E2E Session Test

    st0012/cctop

    A skill your agent uses when smoke-testing cctop end to end — verifying a real coding-agent session is tracked and shows in the panel.

    154 GitHub stars~727 tokensUpdated 6 days ago
    Auto-check passed

  • Video Assets

    st0012/cctop

    A skill your agent uses when publishing, replacing, auditing, or linking cctop promo/demo video assets through GitHub Releases, especially the non-latest media-assets release.

    154 GitHub stars~1.4k tokensUpdated 6 days ago
    Auto-check passed

  • Release

    st0012/cctop

    A skill your agent uses when cutting or preparing a cctop release - "cut a release", "release vX.Y.Z", "prepare a release", "bump the version and tag", "ship a new version".

    154 GitHub stars~1.4k tokensUpdated 6 days ago
    Auto-check passed

  • Video Storyboard

    st0012/cctop

    A skill your agent uses when designing, scripting, or storyboarding a short demo, launch, explainer, or marketing video (especially for a developer tool, app, or SaaS), OR when auditing, critiquing…

    154 GitHub stars~3.4k tokensUpdated 6 days ago
    Auto-check passed

  • Cctop Setup

    st0012/cctop

    A skill your agent uses when cctop-hook command fails or is not found.

    154 GitHub stars~335 tokensUpdated 6 days ago
    Auto-check passed

  • Cctop Restart

    st0012/cctop

    Restart cctop for local development and testing. An agent skill from st0012/cctop.

    154 GitHub stars~395 tokensUpdated 6 days ago
    Auto-check passed

Works with

Categories

Questions about Swiftui Debugging

What does Swiftui Debugging do?

A skill your agent uses when debugging SwiftUI issues in this macOS app — views not updating, layout problems, unnecessary re-renders, state ownership bugs, Preview crashes, or NSHostingView/NSPanel…. Swiftui Debugging is an agent skill from st0012/cctop. Use when debugging SwiftUI issues in this macOS app — views not updating, layout problems, unnecessary re-renders, state ownership bugs, Preview crashes, or NSHostingView/NSPanel quirks.

When should I use Swiftui Debugging?

Swiftui Debugging fits situations like: debugging SwiftUI issues in this macOS app — views not updating; layout problems; unnecessary re-renders; state ownership bugs.

How do I install Swiftui Debugging in Claude Code?

Run `npx skills add st0012/cctop --skill swiftui-debugging -a claude-code`. Or copy the skill folder (.agents/skills/swiftui-debugging in st0012/cctop) into .claude/skills/swiftui-debugging in your project. Claude Code loads it when a task matches its description.

How do I install Swiftui Debugging in Codex?

Run `npx skills add st0012/cctop --skill swiftui-debugging -a codex`. Or copy the skill folder (.agents/skills/swiftui-debugging in st0012/cctop) into .agents/skills/swiftui-debugging in your project. Codex loads it when a task matches its description.

Can I use Swiftui Debugging in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add st0012/cctop --skill swiftui-debugging -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/swiftui-debugging, .gemini/skills/swiftui-debugging, .github/skills/swiftui-debugging and .opencode/skills/swiftui-debugging in your project.

What does Swiftui Debugging need to run?

SKILL.md names no scripts, command-line tools or credentials: Swiftui Debugging is instructions for the agent only.

Does Swiftui Debugging access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Swiftui Debugging safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Swiftui Debugging use?

Swiftui Debugging is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Swiftui Debugging use?

About 2k tokens (SKILL.md is roughly 7.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Swiftui Debugging?

Skills that share tags, products or a category with Swiftui Debugging: Apple Crash Log .NET Symbolication (dotnet/skills, 5.6k stars), Capture Usage4claude Screenshots (f-is-h/Usage4Claude, 400 stars), macOS Development (KartikLabhshetwar/better-shot, 2.4k stars) and Playback Webview Debugging (sozercan/kaset, 2.4k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Swiftui Debugging?

st0012 (a GitHub user) maintains it in st0012/cctop, which has 154 GitHub stars. The repository holds 7 skills in this directory. The repository was last updated on October 1, 2026.

Source: st0012/cctop on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.