Raycast

Raycast Extension Development

This skill defines the preferred workflow and best practices for building, modifying, and troubleshooting custom Raycast extensions.

1. Scaffolding & Setup

• Preferred Method (Duplication): The fastest way to start a new extension is often duplicating the folder of an existing extension. If you do this, you must carefully update the package.json:
• "name"
• "title"
• "description"
• "author"
• "commands" array (update name, title, and description).
• Standard Method: If not duplicating, use npx @raycast/api@latest create.
• Local Dev: After creating/duplicating, run npm install followed by npm run dev. This automatically installs the extension in the user's Raycast app locally and starts the build watcher.

2. General UI & UX Requirements

When modifying or creating forms and commands, adhere to these standards:

• Clean Inputs: Do not set defaultValue with placeholder characters (e.g., - for bullet points) unless explicitly requested.
• Auto-Close on Success: After successfully completing an action (like adding a Notion page, running a system script, etc.), the extension should disappear and return the user to the root Raycast search, rather than retaining the form on-screen.
• Import: import { popToRoot } from "@raycast/api";
• Execute: await popToRoot({ clearSearchBar: true });
• Icon Changes: If an extension's icon is modified (e.g., extension-icon.png), the Raycast app must be fully restarted to reflect the change. Always explicitly alert the user to "Restart Raycast" when you modify an icon.

3. Data Fetching & State

• Use @raycast/utils: For dynamic data fetching (e.g., loading dropdown options from a Notion database, or fetching Spotify tracks), rely on useCachedPromise from the @raycast/utils library. This ensures fast initial loads and proper caching.
• Dynamic Forms: For fields like Notion's select, multi_select, or integrations with existing playlists, dynamic Form.TagPicker or Form.Dropdown components should be populated via useCachedPromise rather than hardcoding.

4. Automation & Local Execution

When an extension requires triggering local MacOS functionality (where external APIs fall short or aren't applicable):

• AppleScript & Keyboard Maestro: Use Node's child_process.exec to run osascript.
• Example: exec('osascript -e \'tell application "Keyboard Maestro Engine" to do script "MACRO_ID"\'')
• Clipboard Operations: Always use the native Clipboard utilities from @raycast/api (e.g., Clipboard.copy(text)) rather than custom bash scripts.

5. Preferences & Authentication

When building an extension that requires an external API (like Notion or Spotify):

• Add the required secrets/tokens to the preferences array in package.json.
• User Instructions: You must proactively remind the user to configure the token when they first load the extension. For example, provide a short snippet:

> ⚠️ Integration Required > You need to provide this extension with an API Token. > 1. Go to [Link to API dashboard] > 2. Create a new token. > 3. Open Raycast, run this new command, and paste the Token in the preferences when prompted.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: adriangrantdotorg
• Source: adriangrantdotorg/Raycast-Skill
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.