An Agent Skill for designing cross-platform desktop apps that feel native — distilled from Raycast's 2.0 technical deep-dive and grounded in reverse-engineering of the shipping Raycast Beta.app binary.
Two goals usually pull against each other: convenient cross-platform development, and near-native performance. This skill captures the structural choices — eight architectural tenets, a four-layer architecture, a WebKit/WebView2 survival guide, a 75-item ship audit — that let an app have both.
What this is
A reference for architects, tech leads, and engineers who must build a desktop app that:
runs on macOS + Windows (optionally Linux) from a single UI codebase,
launches in under 500 ms and stays under 500 MB resident,
is indistinguishable from a native app to its users (no
cursor: pointertell-tales, no white-flash on launch, no WebKit context menu, no smooth-scroll JS),supports a plugin/extension ecosystem in TypeScript,
can share performance-critical code with iOS and a server backend.
This is the four-layer architecture: native shell → system WebView (WKWebView/WebView2) → Node backend → Rust core, wired together with a single typed IPC schema that generates clients for every runtime.
What this is not
Not for single-OS apps (just build native).
Not for Electron-style "good enough" apps (the polish budget here is 5–10× higher).
Not for apps with strict <150 MB or <100 ms cold-start budgets (the floor is real).
Not for games, document editors, or media players.
Run checklists/decision-tree.md to find out if this architecture is even right for your project. It rules itself out for several common cases — saying so directly is more useful than over-fitting advice.
Philosophy
The central tension this architecture resolves: how can a desktop app deliver convenient cross-platform development AND near-native performance, when those goals usually pull against each other? Eight tenets name the structural moves:
Place the seam at the rendering surface — share above the WebView, diverge below it; this is the only altitude where both DX and native feel survive.
One schema, many languages — pay the polyglot tax once at the declaration, never at the call site.
Adopt the platform; don't compete with it — the OS draws blur, scrolling, materials, and dark mode better than you can.
Performance is a property of perception — what the user feels, not what Activity Monitor reports.
The short iteration loop is the product — 200 ms hot reload vs 30 s native rebuild is a 150× compounding advantage.
Cross boundaries intentionally — IPC has a cost; design every crossing as async, batched, schema-typed.
Identity is muscle memory — the hotkey, the rank order, the verbs are the app; everything else is implementation.
Separate baseline from margin — the WebView+Node floor is rented; only your dirty pages are yours to optimize.
Read references/01-philosophy.md first. Everything else is consequence.
About Agent Skills
Agent Skills are the emerging standard for packaging domain knowledge that any compatible agent (Claude Code, the Claude Agent SDK, or other Agent-Skill-aware runtimes) can discover and load. Once installed via the prompt at the top of this README, the skill activates automatically when the agent's conversation touches cross-platform desktop architecture, WebView quirks, or Raycast-style apps — the trigger conditions are declared in SKILL.md's frontmatter.
Sources
Raycast's public technical post: A Technical Deep Dive into the New Raycast
Reverse engineering of
Raycast Beta.appv0.60.0 (macOS 26+ build, Xcode 17, arm64) — seereferences/07-evidence-raycast.mdfor what was found and how.