raycast
GitHub提供Raycast扩展开发的最佳实践，涵盖脚手架搭建、UI/UX规范（如自动关闭、图标重启提示）、数据缓存及本地自动化执行。适用于创建、更新或调试集成API或脚本的扩展。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill raycast -g -y
SKILL.md
Frontmatter
{
"name": "raycast",
"description": "Best practices and workflows for developing and modifying Raycast Extensions (React\/Node). Use when the user asks to create, update, or troubleshoot a Raycast extension, whether it interfaces with external APIs (Notion, Spotify) or executes local scripts (AppleScript, Keyboard Maestro)."
}
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 (updatename,title, anddescription).
- Standard Method: If not duplicating, use
npx @raycast/api@latest create. - Local Dev: After creating/duplicating, run
npm installfollowed bynpm 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
defaultValuewith 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 });
- Import:
- 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 onuseCachedPromisefrom the@raycast/utilslibrary. This ensures fast initial loads and proper caching. - Dynamic Forms: For fields like Notion's
select,multi_select, or integrations with existing playlists, dynamicForm.TagPickerorForm.Dropdowncomponents should be populated viauseCachedPromiserather 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.execto runosascript.- Example:
exec('osascript -e \'tell application "Keyboard Maestro Engine" to do script "MACRO_ID"\'')
- Example:
- Clipboard Operations: Always use the native
Clipboardutilities 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
preferencesarray inpackage.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.
- Go to [Link to API dashboard]
- Create a new token.
- Open Raycast, run this new command, and paste the Token in the preferences when prompted.
Version History
- e0220ca Current 2026-07-05 23:30
