native-feel-skill: Raycast's Desktop Architecture, Distilled Into a Skill

Cross-platform convenience and native polish usually trade off — pick Electron and ship fast but feel web-y, pick native and pay per platform. yetone/native-feel-skill refuses the trade-off: an agent skill distilled from Raycast's public technical deep-dive and reverse-engineering of the shipping Raycast Beta.app binary, packaging the structural choices that let one UI codebase pass for a real Mac app.

Why This Skill Matters

The kit has four parts: eight architectural tenets (place the seam at the rendering surface; one schema, many languages; adopt the platform rather than compete with it), a four-layer architecture — native shell (Swift/AppKit, C#/WPF) over a system WebView (WKWebView/WebView2) over a Node backend over a Rust core, wired with one typed IPC schema — a WebKit/WebView2 survival guide the README calls the goldmine, and a 75-item ship-readiness audit plus a decision tree that rules the architecture out for common cases.

The honesty is part of the design: the decision tree tells you not to use this if you need sub-100 ms cold starts, a sub-150 MB memory floor, or a three-month runway — "saying so directly is more useful than over-fitting advice." The stated targets: under 500 ms launch, under 500 MB resident, indistinguishable from native.

Installation

One command installs globally for any compatible agent:

npx skills add yetone/native-feel-skill -g

Or paste the README's install prompt to your agent — it clones the repo into your skills directory and verifies SKILL.md plus the references/ and checklists/ folders landed.

Real Workflow: Rescue an Electron App That Feels Web-y

Ask the agent to audit, and the skill goes straight to the 75-item checklist (checklists/ship-readiness.md). The README's own example lists the usual offenders — most Electron apps fail the same six to eight items: cursor: pointer on rows, web-style modal overlays instead of native sheets, hardcoded brand accent instead of the system accent, page fade transitions, opaque window background instead of platform material, the WebKit context menu still firing. Each is a 5-to-30-minute fix, and together they get you most of the way to what the README calls the 30-second skeptical-user test.

Then ask the bigger question: if "indistinguishable" means Liquid Glass materials and sub-200 ms launches, the README is blunt that Electron has a ceiling — that is what the four-layer architecture and the decision tree are for.

Tips

• Run checklists/decision-tree.md before committing to the architecture; it rules itself out honestly.
• Read references/01-philosophy.md first — "everything else is consequence."
• The reference files map to real debugging questions: WKWebView flicker, typed IPC across Rust/Swift/TypeScript, and why Activity Monitor lies about memory.
• The audit is also useful as a one-shot review: point the agent at any web-wrapped app and ask for the failed items.

When Not to Use This

The README's own exclusion list is the boundary: single-OS apps (just build native), Electron-style "good enough" products (the polish budget here is 5-10× higher), strict resource budgets, games and media players. And the architecture encodes Raycast's scale — adopting all four layers for a two-person utility tool is buying a building for a kiosk.

See the leaderboard for more skills.