Raycast Automator

Build Raycast extensions and script commands from natural language task descriptions. Handles the full lifecycle: analysis, code generation, setup, and dev launch.

Output Directory

All output goes to ~/Documents/raycast-scripts/:

• Script commands: files directly in the root (e.g., my-script.sh)
• Extensions: subdirectories (e.g., my-extension/src/index.tsx)

Create the directory if it doesn't exist. For extensions, create the subdirectory named after the extension.

Decision Flow

User describes a task
  │
  ├─ Analyze complexity
  │   ├─ Needs rich UI (lists, forms, grids, detail views)?  → Extension
  │   ├─ Needs OAuth or token management?                     → Extension
  │   ├─ Needs persistent state across runs?                  → Extension
  │   ├─ Needs menu bar presence?                             → Extension
  │   ├─ Needs pagination or streaming data?                  → Extension
  │   ├─ Simple system operation (open, toggle, copy)?        → Script Command
  │   ├─ Opens URL or does clipboard work?                    → Script Command
  │   ├─ Runs a shell command or API call with simple output? → Script Command
  │   └─ 1-3 simple text inputs, no interactive UI?           → Script Command
  │
  ├─ Present recommendation with reasoning to user
  ├─ User confirms or overrides
  │
  ├─ IF Script Command:
  │   ├─ Pick language:
  │   │   ├─ macOS + simple task       → Bash
  │   │   ├─ Windows + simple task     → Batch/PowerShell
  │   │   ├─ Complex logic / API calls → Python
  │   │   └─ Mac-native automation     → AppleScript
  │   ├─ Generate script with full metadata block
  │   ├─ chmod +x the file
  │   ├─ Ensure ~/Documents/raycast-scripts/ is created
  │   └─ Tell user to add script directory in Raycast if first time
  │
  └─ IF Extension:
      ├─ Scaffold project structure
      ├─ Generate package.json with full manifest
      ├─ Generate src/ entry point(s)
      ├─ Run npm install
      ├─ Run npm run dev
      └─ Confirm extension appears in Raycast

Before Writing Code

1. Read the reference files in reference/ directory of this skill:

   • reference/extension-api.md - for extensions (manifest, UI components, hooks, APIs)
   • reference/script-commands.md - for script commands (metadata, templates, examples)
   • reference/patterns.md - for best practices and common patterns

2. Check platform: Use uname to detect macOS vs other. This affects:

   • Script language defaults (bash vs bat)
   • Available APIs (MenuBarExtra, BrowserExtension are macOS-only)
   • AppleScript availability

Script Command Generation

Required metadata block (ALWAYS include all of these):

#!/bin/bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title <Title Case Name>
# @raycast.mode <silent|compact|fullOutput|inline>

# Optional parameters:
# @raycast.packageName <Category>
# @raycast.icon <emoji or path>
# @raycast.description <What it does>
# @raycast.needsConfirmation <true for destructive ops>
# @raycast.argument1 { "type": "text", "placeholder": "..." }

Mode selection:

Language shebangs:

Argument access by language:

Script rules:

• Max 3 arguments per script
• Use percentEncoded: true for URL arguments
• Use needsConfirmation: true for destructive operations
• Non-zero exit code = failure (last line becomes error message)
• Scripts run in non-login shell; use #!/bin/bash -l if login shell needed
• inline mode REQUIRES refreshTime (min 10s)
• Use absolute paths since PATH may differ from user's shell

Extension Generation

Minimum project structure:

extension-name/
├── package.json          # Manifest (see reference/extension-api.md)
├── tsconfig.json         # TypeScript config
├── src/
│   └── index.tsx         # Main command entry point
└── assets/
    └── icon.png          # 512x512 PNG (or use command-icon.png)

package.json template:

{
  "$schema": "https://www.raycast.com/schemas/extension.json",
  "name": "extension-name",
  "title": "Extension Title",
  "description": "What it does",
  "icon": "command-icon.png",
  "author": "author-name",
  "categories": ["Productivity"],
  "license": "MIT",
  "platforms": ["macOS"],
  "commands": [
    {
      "name": "index",
      "title": "Command Title",
      "description": "What the command does",
      "mode": "view"
    }
  ],
  "dependencies": {
    "@raycast/api": "^1.98.0",
    "@raycast/utils": "^1.19.0"
  },
  "devDependencies": {
    "@raycast/eslint-config": "^1.0.11",
    "typescript": "^5.4.5",
    "@types/node": "22.14.0",
    "@types/react": "19.0.0",
    "eslint": "^8.57.0"
  },
  "scripts": {
    "build": "ray build",
    "dev": "ray dev",
    "fix-lint": "ray lint --fix",
    "lint": "ray lint",
    "prepublishOnly": "echo \"Error: no publish script\" && exit 1",
    "publish": "npx @raycast/api@latest publish"
  }
}

tsconfig.json template:

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "compilerOptions": {
    "lib": ["ES2023"],
    "module": "Node16",
    "moduleResolution": "node16",
    "target": "ES2022",
    "resolveJsonModule": true,
    "strict": true,
    "jsx": "react-jsx"
  },
  "include": ["src/**/*", "env.d.ts", "raycast-env.d.ts"]
}

Command modes:

Choosing the right UI component:

Essential hooks (from @raycast/utils):

Extension rules:

• Always set isLoading prop on top-level components during async ops
• Use showToast(Toast.Style.Failure) for errors, not console.error
• Use showFailureToast from @raycast/utils for standardized errors
• First action in ActionPanel = primary (Enter key)
• Use