---

name: raycast-extensions description: Build and maintain Raycast extensions using the Raycast API. Triggers on @raycast/api, List, Grid, Detail, Form, AI.ask, LocalStorage, Cache, showToast, and BrowserExtension. Use this repo's references/api/*.md files as the primary source of truth for component specs and API usage.

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.
2. Consult Reference: Open and read the corresponding file in references/api/ (e.g., references/api/list.md).
3. 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.
5. 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.

• List Reference | Grid Reference

<List isLoading={isLoading} searchBarPlaceholder="Search items..." throttle>
  <List.Item
    title="Item Title"
    subtitle="Subtitle"
    accessories={[{ text: "Tag" }]}
    actions={
      <ActionPanel>
        <Action.Push title="View Details" target={<Detail markdown="# Details" />} />
        <Action.CopyToClipboard title="Copy" content="value" />
      </ActionPanel>
    }
  />
</List>

2. Detail (Rich Markdown)

Use for displaying long-form content or item details.

• Detail Reference

<Detail
  isLoading={isLoading}
  markdown="# Heading\nContent here."
  metadata={
    <Detail.Metadata>
      <Detail.Metadata.Label title="Status" text="Active" icon={Icon.Checkmark} />
    </Detail.Metadata>
  }
/>

3. Form (User Input)

Always include a SubmitForm action.

• Form Reference

<Form
  actions={
    <ActionPanel>
      <Action.SubmitForm onSubmit={(values) => console.log(values)} />
    </ActionPanel>
  }
>
  <Form.TextField id="title" title="Title" placeholder="Enter title" />
  <Form.TextArea id="description" title="Description" />
</Form>

4. Feedback & Interactivity

Prefer showToast for most feedback.

• Toast Reference | HUD Reference

// Success/Failure
await showToast({ style: Toast.Style.Success, title: "Success!" });

// HUD (Overlay)
await showHUD("Done!");

5. Data Persistence

Use Cache for performance, LocalStorage for persistence.

• Cache Reference | Storage Reference

// Cache (Sync/Transient)
const cache = new Cache();
cache.set("key", "value");

// LocalStorage (Async/Persistent)
await LocalStorage.setItem("key", "value");

6. AI & Browser Extension (Restricted APIs)

Always wrap in environment.canAccess checks.

• AI Reference | Browser Reference

if (environment.canAccess(AI)) {
  const result = await AI.ask("Prompt");
}

if (environment.canAccess(BrowserExtension)) {
  const tabs = await BrowserExtension.getTabs();
}

Additional Resources

API Reference Tree

• UI Components
  • Action Panel
  • Detail
  • Form
  • Grid
  • List
  • User Interface
• Interactivity
  • Actions
  • Alert
  • Keyboard
  • Navigation
  • Raycast Window Search Bar
• Utilities & Services
  • AI
  • Browser Extension
  • Clipboard
  • Environment
  • Feedback & HUD
    • HUD
    • Toast
  • OAuth
  • System Utilities
• Data & Configuration
  • Caching
  • Colors
  • Icons & Images
  • Preferences
  • Storage
• Advanced
  • Command Related Utilities
  • Menu Bar Commands
  • Tool
  • Window Management

Examples

For end-to-end examples combining multiple components and APIs, see examples.md.