Raycast Extensions

Raycast Extensions

Build new Raycast extensions, extend or fix existing ones, and review them against the Raycast Store guidelines - using @raycast/api, @raycast/utils (v2), React 19, TypeScript, and ESLint 10 flat config. Check the extension's package.json for the exact @raycast/api version (pin the latest for Store submissions).

Operating rules

• Prefer official docs when uncertain: developers.raycast.com (API + guides) and manual.raycast.com/extensions-guidelines (the real review bar). Imitate real extensions in github.com/raycast/extensions - CONTRIBUTING.md is a thin stub; the conventions live in the source and the docs.
• Use the @raycast/utils hooks for all data fetching - never hand-roll useEffect + fetch + useState. The hooks give isLoading, error toasts, caching, abort, revalidate, mutate, and pagination for free, and reviewers reject the hand-rolled version.
• Don't reinvent the framework: use the preferences API for config (not extra commands), useNavigation/Action.Push for navigation (not a custom stack), and showFailureToast for errors (not bespoke failure toasts). These are explicit store-review rules.
• Secrets never go in source: use password-type preferences or OAuth (OAuthService). Hardcoded keys or Keychain access are auto-rejected.
• This skill covers the framework, not any one service's API. When wiring a third-party API, confirm its current endpoints/SDK rather than guessing.

First, decide which mode you're in

1. New extension - scaffold from a template, then build commands. Start at Build workflow.
2. Extend / fix an existing one - read the extension's existing structure first and match its conventions (its client singleton, its hooks/, its error helper). Add a CHANGELOG entry. Don't impose a different architecture.
3. Review an existing extension (for store-readiness or a PR) - go to Review workflow and apply references/store-review.md.

If the user's intent is ambiguous (e.g. "help with my Raycast extension"), ask which of these it is before diving in.

Reference map - read the relevant file, don't load everything

The SKILL.md is the spine. Pull in a reference when the task touches it:

evals/ holds this skill's own trigger/behaviour test prompts and is intentionally unrouted (maintainer-facing, not read during a task).

Quick intake (new extension)

Before scaffolding, settle:

• What it does and the commands it needs - each command is one entry point. For each: a view (renders UI), no-view (fire-and-forget action, feedback via showHUD), or menu-bar (MenuBarExtra) command?
• Does the AI need to call it? If a discrete data fetch/mutation would be useful to Raycast AI, expose it as a tool (src/tools/) in addition to or instead of a command. See references/ai-extensions.md.
• Config: API tokens (→ password preference or OAuth), tunables (→ textfield/checkbox/dropdown preferences). Per-run input that belongs in root search → arguments (max 3).
• Data source: REST (useFetch), arbitrary async/SDK (useCachedPromise), local CLI (useExec), local SQLite (useSQL).
• Platforms: macOS only, or macOS + Windows? (Affects platforms and which APIs you can use - runAppleScript is macOS-only.)

Build workflow

1) Scaffold

Preferred: Raycast's in-app "Create Extension" command (pick a template: Detail / List / Grid / Form / Menu Bar; it wires up eslint + tsconfig). CLI alternative: npm init raycast-extension -t <template>. Then npm install.

Requires Raycast 1.26+, a current Node (the @raycast/api engines field tracks the latest LTS - check it and use that Node or newer), and being signed into Raycast.

2) Manifest (package.json)

This is where most mistakes live. Get the structure right from references/manifest.md. The essentials:

• Required root: name (kebab-case slug), title (Title Case display), description, icon (512×512 PNG in assets/), author (Raycast handle), categories (Title Case enum), license: "MIT", commands[]. Add "$schema": "https://www.raycast.com/schemas/extension.json" for editor validation.
• Each command name maps to src/<name>.ts(x) exactly, or the build fails.
• Folder layout matters and trips people up: assets/ = bundled runtime icons; metadata/ = Store screenshots (2000×1250 PNG); media/ = README images only. Don't conflate them.

3) Command code

• View command = a default-exported React component that returns <List>/<Detail>/<Form>/<Grid>. No-view = a default-exported async function. Menu-bar = a component returning <MenuBarExtra>.
• Data layer: reach for the right hook (see table in intake). Wire its isLoading into the top-level view and its pagination into <List pagination>. Put changing inputs in the hook's args array - that array is the cache key and the deps.
• Writes/mutations: use the hook's mutate with an optimisticUpdate and an Animated→Success/Failure toast, inside try/catch.
• Errors: import { showFailureToast } from "@raycast/utils" in every catch. For no-view commands use showHUD (it survives the window closing); showToast disappears with the window.
• Preferences: getPreferenceValues<Preferences>() (types auto-generated into raycast-env.d.ts - never edit that file by hand).
• Full primitives and hook signatures: references/api-and-hooks.md.

4) Architecture (only as it grows)

A single-command extension stays flat: src/index.tsx, maybe api.ts, types.ts, preferences.ts. Once multiple commands share logic, adopt the convention the big extensions (github, linear) converge on:

src/
  <command>.tsx        # one per manifest command; default export
  api/                 # client singleton + raw data fns (getXClient() that throws if uninit)
  hooks/               # use*.ts wrappers over useCachedPromise that call getXClient()
  helpers/             # pure fns: errors.ts (getErrorMessage), icons.ts, dates.ts
  components/          # shared List.Item / Form / actions pieces
  tools/               # one file per AI tool (if any)
  types.ts

The dominant auth pattern: an OAuthService + a module-level client in api/, wrapped with withAccessToken(service) (from @raycast/utils) on each command's default export and on each tool. Only call getXClient() inside a wrapped component/hook/tool - at module top level it throws before auth runs. See references/api-and-hooks.md (OAuth section).

5) Verify before declaring done

Run, in order:

npm run lint        # ray lint  (add --fix to autofix)
npm run build       # ray build -e dist — does a full TypeScript type-check the dev build skips
npm run dev         # ray develop — imports into Raycast with hot reload; actually exercise the command

ray build catches type errors that ray develop lets slide, so always run it before you consider a change finished. Then open the command in Raycast and verify the real behaviour - loading state, empty state, the happy path, and at least one error path.

Review / maintain workflow

When reviewing an existing extension (store-readiness, a PR, or "why is this rejected?"):

1. Read references/store-review.md and apply its review checklist top to bottom.
2. Run ray lint and ray build -e dist - these catch a large fraction of review blockers mechanically.
3. Check the high-frequency rejection causes first: default/dark-mode-broken icon; wrong screenshot size; license not MIT; verb-first or generic title; secrets in source / Keychain access; hand-rolled fetch instead of the hooks; missing or misformatted CHANGELOG.md.
4. For a fix to someone else's extension: add yourself to contributors, add a CHANGELOG entry (## [Title] - {PR_MERGE_DATE} at the top), and keep the diff minimal and on-convention.

Publishing

Canonical commands are the ray-backed package scripts: npm run build, then npm run publish (= npx @raycast/api@latest publish), which opens a PR against raycast/extensions. Two things to flag:

• Store PRs require npm + a committed package-lock.json. The CI uses npm; a pnpm-lock.yaml/yarn.lock in the PR gets it rejected. So even if local dev uses pnpm, generate the lockfile with npm for a Store-bound submission, and surface this to the user before committing a lockfile.
• pnpm publish is a built-in pnpm command that publishes to the npm registry - it does not run Raycast's publish script. If using pnpm locally, invoke pnpm run publish (explicit run) or pnpm dlx @raycast/api@latest publish. The prepublishOnly: "... && exit 1" guard in the manifest exists precisely to stop an accidental npm publish to npmjs.

For org/private extensions, npm run publish goes to the org's private store (no public PR).

High-value pitfalls (the why behind the rules)

• onSearchTextChange silently disables built-in filtering. Once you handle search text yourself, the list stops filtering - either implement server-side search or re-enable filtering. Add throttle if onSearchTextChange does network calls, or you fire a request per keystroke.
• Action order is UX. The first Action is the primary (Enter) action. Put a destructive action first and Enter deletes. Mark destructive actions with style: Action.Style.Destructive and order deliberately. In Form, primary submit is ⌘↵ (Enter inserts a newline), so Action.SubmitForm should be first.
• LocalStorage is async, Cache is sync and string-only. Prefer the useLocalStorage / useCachedState hooks over touching them directly; never store secrets in Cache.
• AI tool Input JSDoc is the model's prompt. The tool's argument schema is derived from a type named exactly Input; the JSDoc on each field is what the model reads to choose arguments. Thin descriptions cause wrong calls. Every mutating tool needs an exported confirmation.
• {PR_MERGE_DATE} is a literal placeholder, not a date you fill in - Raycast substitutes the merge date. Hardcoding a date is a common review nit.

When you finish a build or a review, state plainly what you verified (lint/build clean, command exercised in Raycast, which paths you checked) rather than asserting it works untested.