agentleFS
AdhamxonAdhamxon/claude-code-skills/.claude/skills/macos-menubar-tuist-app/SKILL.md

macos-menubar-tuist-app

Skill2 starsChanged 4 months agoMITView on GitHub

Build, refactor, or review macOS menubar apps that use Tuist and SwiftUI. Use when creating or maintaining LSUIElement menubar utilities, defining Tuist targets/manifests, implementing model-client-store-view architecture, adding script-based launch flows, or validating reliable local build/run behavior without Xcode-first workflows.

2 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

28 rules. About 0 are common, 18 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈18

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Keep the app menubar-only unless explicitly told otherwise.

    line 12
  2. Distinctive:

    Keep transport and decoding logic outside views.

    line 13
  3. Very specific:

    Keep state transitions in a store layer (@Observable or equivalent), not in row/view presentation code.

    line 14
  4. Distinctive:

    Keep model decoding resilient to API drift: optional fields, safe fallbacks, and defensive parsing.

    line 15
  5. Distinctive:

    Treat Tuist manifests as the source of truth.

    line 16
  6. Very specific:

    Prefer script-based launch for local iteration when tuist run is unreliable for macOS target/device resolution.

    line 17
  7. Very specific:

    Prefer tuist xcodebuild build over raw xcodebuild in local run scripts when building generated projects.

    line 18
  8. Distinctive:

    Use this placement by default:

    line 22
  9. Very specific:

    Verify Tuist.swift and Project.swift (or workspace manifests) exist.

    line 36
  10. Distinctive:

    Read existing run scripts before changing launch behavior.

    line 37
  11. Very specific:

    Use curl to verify endpoint shape, auth requirements, and pagination behavior.

    line 40
  12. Very specific:

    If endpoint ignores limit/page, implement full-list handling with local trimming in the store.

    line 41
  13. Distinctive:

    Add or update client request/decoding logic.

    line 45
  14. Distinctive:

    Update store refresh, filtering, and cache policy.

    line 46
  15. Distinctive:

    Keep app wiring minimal

    line 49
  16. Distinctive:

    Keep app entry focused on scene/menu wiring and dependency injection.

    line 50
  17. Very specific:

    Avoid embedding business logic in App or menu scene declarations.

    line 51
  18. Distinctive:

    Ensure run script restarts an existing instance before relaunching.

    line 54
  19. Distinctive:

    Ensure run script does not open Xcode as a side effect.

    line 55
  20. Very specific:

    Use tuist generate --no-open when generation is required.

    line 56
  21. Very specific:

    When the run script builds the generated project, prefer TUIST_SKIP_UPDATE_CHECK=1 tuist xcodebuild build ...

    line 57
  22. Distinctive:

    Run validations after edits:

    line 61
  23. Distinctive:

    If launch workflow changed:

    line 67
  24. Distinctive:

    If shell scripts changed:

    line 73
  25. Distinctive:

    Use run/stop scripts as canonical local run path.

    line 84
  26. Distinctive:

    Keep network and state logic out of SwiftUI view bodies.

    line 98
  27. Distinctive:

    Keep Tuist manifests and run scripts aligned with actual build/run flow.

    line 99
  28. Distinctive:

    Run the validation matrix for touched areas.

    line 100

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

macos-menubar-tuist-app

Build and maintain macOS menubar apps with a Tuist-first workflow and stable launch scripts. Preserve strict architecture boundaries so networking, state, and UI remain testable and predictable.

Core Rules

  • Keep the app menubar-only unless explicitly told otherwise. Use LSUIElement = true by default.
  • Keep transport and decoding logic outside views. Do not call networking from SwiftUI view bodies.
  • Keep state transitions in a store layer (@Observable or equivalent), not in row/view presentation code.
  • Keep model decoding resilient to API drift: optional fields, safe fallbacks, and defensive parsing.
  • Treat Tuist manifests as the source of truth. Do not rely on hand-edited generated Xcode artifacts.
  • Prefer script-based launch for local iteration when tuist run is unreliable for macOS target/device resolution.
  • Prefer tuist xcodebuild build over raw xcodebuild in local run scripts when building generated projects.

Expected File Shape

Use this placement by default:

  • Project.swift: app target, settings, resources, Info.plist keys
  • Sources/*Model*.swift: API/domain models and decoding
  • Sources/*Client*.swift: requests, response mapping, transport concerns
  • Sources/*Store*.swift: observable state, refresh policy, filtering, caching
  • Sources/*Menu*View*.swift: menu composition and top-level UI state
  • Sources/*Row*View*.swift: row rendering and lightweight interactions
  • run-menubar.sh: canonical local restart/build/launch path
  • stop-menubar.sh: explicit stop helper when needed

Workflow

  1. Confirm Tuist ownership
  • Verify Tuist.swift and Project.swift (or workspace manifests) exist.
  • Read existing run scripts before changing launch behavior.
  1. Probe backend behavior before coding assumptions
  • Use curl to verify endpoint shape, auth requirements, and pagination behavior.
  • If endpoint ignores limit/page, implement full-list handling with local trimming in the store.
  1. Implement layers from bottom to top
  • Define/adjust models first.
  • Add or update client request/decoding logic.
  • Update store refresh, filtering, and cache policy.
  • Wire views last.
  1. Keep app wiring minimal
  • Keep app entry focused on scene/menu wiring and dependency injection.
  • Avoid embedding business logic in App or menu scene declarations.
  1. Standardize launch ergonomics
  • Ensure run script restarts an existing instance before relaunching.
  • Ensure run script does not open Xcode as a side effect.
  • Use tuist generate --no-open when generation is required.
  • When the run script builds the generated project, prefer TUIST_SKIP_UPDATE_CHECK=1 tuist xcodebuild build ... instead of invoking raw xcodebuild directly.

Validation Matrix

Run validations after edits:

TUIST_SKIP_UPDATE_CHECK=1 tuist xcodebuild build -scheme <TargetName> -configuration Debug

If launch workflow changed:

./run-menubar.sh

If shell scripts changed:

bash -n run-menubar.sh
bash -n stop-menubar.sh
./run-menubar.sh

Failure Patterns and Fix Direction

  • tuist run cannot resolve the macOS destination: Use run/stop scripts as canonical local run path.
  • Menu UI is laggy or inconsistent after refresh: Move derived state and filtering into the store; keep views render-only.
  • API payload changes break decode: Relax model decoding with optional fields and defaults, then surface missing data safely in UI.
  • Feature asks for quick UI patch: Trace root cause in model/client/store before changing row/menu presentation.

Completion Checklist

  • Preserve menubar-only behavior unless explicitly changed.
  • Keep network and state logic out of SwiftUI view bodies.
  • Keep Tuist manifests and run scripts aligned with actual build/run flow.
  • Run the validation matrix for touched areas.
  • Report concrete commands run and outcomes.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.