Raycast Extensions Skill
Build powerful extensions with React, TypeScript, and the Raycast API.
Quick Start (Agent Workflow)
Follow these steps when tasked with implementing or fixing Raycast features:
- 1. Identify the core component: Determine if the UI needs a
List, Grid, Detail, or Form. - Consult Reference: Open and read the corresponding file in
references/api/ (e.g., references/api/list.md). - Use Defaults:
-
Feedback: Use
showToast for Loading/Success/Failure. Use
showHUD only for quick background completions.
-
Data: Use
Cache for frequent/transient data,
LocalStorage for persistent user data.
-
Access: Always check
environment.canAccess(AI) or
environment.canAccess(BrowserExtension) before use.
- 4. Implementation: Provide a concise implementation using
@raycast/api components. - Citing: Link back to the specific
references/api/*.md file you used.
Cookbook Patterns
1. List & Grid (Searchable UI)
Use
List for text-heavy data and
Grid for image-heavy data.
CODEBLOCK0
2. Detail (Rich Markdown)
Use for displaying long-form content or item details.
CODEBLOCK1
3. Form (User Input)
Always include a
SubmitForm action.
CODEBLOCK2
4. Feedback & Interactivity
Prefer
showToast for most feedback.
CODEBLOCK3
5. Data Persistence
Use
Cache for performance,
LocalStorage for persistence.
CODEBLOCK4
6. AI & Browser Extension (Restricted APIs)
Always wrap in
environment.canAccess checks.
CODEBLOCK5
Additional Resources
API Reference Tree
-
Action Panel
-
Detail
-
Form
-
Grid
-
List
-
User Interface
-
Actions
-
Alert
-
Keyboard
-
Navigation
-
Raycast Window Search Bar
-
AI
-
Browser Extension
-
Clipboard
-
Environment
-
Feedback & HUD
-
HUD
-
Toast
-
OAuth
-
System Utilities
-
Caching
-
Colors
-
Icons & Images
-
Preferences
-
Storage
-
Command Related Utilities
-
Menu Bar Commands
-
Tool
-
Window Management
Examples
For end-to-end examples combining multiple components and APIs, see examples.md.
Raycast 扩展技能
使用 React、TypeScript 和 Raycast API 构建强大的扩展。
快速入门（智能体工作流程）
当需要实现或修复 Raycast 功能时，请遵循以下步骤：
- 1. 识别核心组件：确定 UI 需要 List、Grid、Detail 或 Form。
- 查阅参考：打开并阅读 references/api/ 中对应的文件（例如 references/api/list.md）。
- 使用默认方案：
-
反馈：使用 showToast 显示加载/成功/失败状态。仅在快速后台完成时使用 showHUD。
-
数据：使用 Cache 处理频繁/临时数据，使用 LocalStorage 处理持久化用户数据。
-
访问权限：使用前务必检查 environment.canAccess(AI) 或 environment.canAccess(BrowserExtension)。
- 4. 实现：使用 @raycast/api 组件提供简洁的实现。
- 引用：链接回你使用的具体 references/api/*.md 文件。
示例模式
1. 列表与网格（可搜索 UI）
使用 List 处理文本密集型数据，使用 Grid 处理图片密集型数据。
tsx
title=项目标题
subtitle=副标题
accessories={[{ text: 标签 }]}
actions={
} />
}
/>
2. 详情（富文本 Markdown）
用于显示长内容或项目详情。
tsx
isLoading={isLoading}
markdown=# 标题\n此处内容。
metadata={
}
/>
3. 表单（用户输入）
始终包含 SubmitForm 操作。
tsx
actions={
console.log(values)} />
}
4. 反馈与交互
大多数反馈优先使用 showToast。
typescript
// 成功/失败
await showToast({ style: Toast.Style.Success, title: 成功！ });
// HUD（覆盖层）
await showHUD(完成！);
5. 数据持久化
使用 Cache 提升性能，使用 LocalStorage 实现持久化。
typescript
// 缓存（同步/临时）
const cache = new Cache();
cache.set(key, value);
// 本地存储（异步/持久化）
await LocalStorage.setItem(key, value);
6. AI 与浏览器扩展（受限 API）
始终使用 environment.canAccess 进行检查。
typescript
if (environment.canAccess(AI)) {
const result = await AI.ask(提示词);
}
if (environment.canAccess(BrowserExtension)) {
const tabs = await BrowserExtension.getTabs();
}
附加资源
API 参考树
-
操作面板
-
详情
-
表单
-
网格
-
列表
-
用户界面
-
操作
-
警告
-
键盘
-
导航
-
Raycast 窗口搜索栏
-
AI
-
浏览器扩展
-
剪贴板
-
环境
-
反馈与 HUD
-
HUD
-
Toast
-
OAuth
-
系统工具
-
缓存
-
颜色
-
图标与图片
-
偏好设置
-
存储
-
命令相关工具
-
菜单栏命令
-
工具
-
窗口管理
示例
如需查看结合多个组件和 API 的端到端示例，请参阅 examples.md。
