---
name: raycast
description: >-
Operate Raycast on Jack's Mac via deeplinks, Script Commands, AI
providers.yaml/Skills/Commands/Agents, PromptLab, clipboard history, or
Superwhisper toggle. Delegate Autohub script install to raycast-autojack.
license: MIT
tags:
- raycast
- desktop
- macos
- deeplink
- script-commands
- ai
- autohub
agents:
- claude-code
- codex
- autojack
category: desktop
metadata:
version: "1.0.0"
app_bundle: com.raycast.macos
app_path: /Applications/Raycast.app
related_skill: raycast-autojack
capabilities:
network: false
filesystem: readwrite
tools:
- Bash
- Python
requires-secrets: []
resources:
- path: references/control-surfaces.md
type: file
- path: references/ai-config.md
type: file
- path: references/troubleshooting.md
type: file
---raycast
Drive Raycast from agents without a first-party ops CLI and without
an MCP. There is no FlashSpace-style inventory CLI. npx ray is for
extension authors (build/lint), not day-to-day control. Do not
build a Raycast MCP unless a real control API appears — it would only
wrap the same deeplinks/files.
Sibling skill: raycast-autojack owns Autohub raycast/ install,
doctor, sync, smoke. This skill owns general Raycast operation +
file-native AI config.
When to use
| User intent | Do this | Details |
|---|---|---|
| "Open clipboard history / paste queue" | deeplink built-in clipboard commands | references/control-surfaces.md |
| "Run Raycast command X" | Copy/construct deeplink → open | references/control-surfaces.md |
| "Add/edit a Script Command" | write file under Script Directory | references/control-surfaces.md |
| "Point Raycast AI at AutoJack" | edit providers.yaml | references/ai-config.md |
| "Reusable AI instructions as code" | write Raycast AI Skills (SKILL.md) | references/ai-config.md |
| "One-shot AI prompt as a command" | AI Commands JSON → Import AI Commands | references/ai-config.md |
| "Change my Agent preset instructions" | draft text; Jack applies in Settings → AI → Agents | references/ai-config.md |
| "Install Autohub quick-reply / voice-note scripts" | raycast-autojack skill | see below |
| "Something isn't working / verify setup" | run Doctor, check the symptom table | references/troubleshooting.md |
| "Configure every extension pref / Agent UI field" | cannot fully automate — open settings, assist | — |
Safety / autonomy
| Class | Ops | Policy |
|---|---|---|
| 🟢 Green | Inventory manifests; open known-safe deeplinks; read providers.yaml structure (redact secrets); list Script Directories; draft AI Skills / AI Command JSON | Run freely |
| 🟡 Yellow | Edit Script Commands; edit providers.yaml models/base_url; write AI Skills under ~/.config/raycast/skills; open Import/Create AI Command UI; deeplinks that change app state (mute, caffeinate, send Slack, …) | State intent; proceed if clear |
| 🔴 Red | Paste/read API keys into chat; rewrite .rayconfig bulk import blindly; delete Agents/commands en masse; edit encrypted SQLite under Application Support; change OAuth tokens in prefs | Always confirm; never dump secrets |
Never print ~/.config/raycast/config.json or raw API keys from
providers.yaml into the conversation.
Architecture (what is / isn't agent-writable)
Supported config surfaces
| Asset | Path / mechanism | Writable? |
|---|---|---|
| Deeplink launch | raycast://extensions/<author>/<ext>/<cmd> | Invoke only |
| Script Commands | e.g. ~/Documents/Raycast Scripts/ | Yes (files) |
| AI providers | ~/.config/raycast/ai/providers.yaml | Yes (YAML) |
| AI Skills | ~/.config/raycast/skills/<name>/SKILL.md (+ default scan dirs) | Yes |
| AI Commands | UI create/edit; Import AI Commands from JSON | Draft + import |
| Agents (ex-Presets) | Settings → AI → Agents; ray.so/presets | UI / share links |
| Personalization | Settings → AI → Personalization | UI |
| Extension preferences | Raycast Settings → Extensions | UI (no write API) |
| Bulk backup | Export/Import Preferences & Data (.rayconfig) | UI, coarse |
Not supported (don't fake it)
- Programmatic CRUD of every extension preference
- Silent Store install + OAuth without user
- Reading live Raycast UI state from
raycast-enc.sqlite - Treating plist keys under
com.raycast.macosas a stable API
Autohub Raycast scripts (`raycast-autojack`)
Repo path: autohub/raycast/ — quick-reply.js, context-reply.js,
voice-note-raycast.js, summon-autojack.js, install.sh, …
# from autohub repo root, via the dedicated skill helper:
autovault skill doctor raycast-autojack --repo .
autovault skill setup raycast-autojack --repo .
autovault skill sync raycast-autojack --repo .
autovault skill smoke raycast-autojack --repo .Do not re-implement installers in this skill; load raycast-autojack.
Anti-patterns
- Do not invent an MCP server that only shells
open raycast://…. - Do not use
npx rayas an ops tool. - Do not cat secrets from
config.json/providers.yamlapi_keys. - Do not hand-edit
raycast-enc.sqliteor treat plist keys as API. - Do not confuse Raycast AI Skills with AutoVault operator skills — different consumers; share formats carefully.
- Do not claim Agents/extension prefs are fully automatable.
- Prefer
flashspaceCLI over FlashSpace Raycast extension for workspace switching when both exist.
Reference files
| File | Read when |
|---|---|
references/control-surfaces.md | Launching a Raycast command (deeplinks, known Autohub deeplinks, installed-extension inventory) or writing/editing a Script Command; also window-management alternatives. |
references/ai-config.md | Configuring Raycast AI: providers.yaml, AI Skills, AI Commands, Agents (presets), Personalization, PromptLab. |
references/troubleshooting.md | Running the Doctor check, or diagnosing a symptom (deeplink/script/AI Skill not working) — plus upstream Raycast doc links. |
Related skills
| Skill | Role |
|---|---|
| raycast (this) | General operate + file-native AI config |
| raycast-autojack | Autohub script install/doctor/sync/smoke |
| flashspace | Virtual workspaces (CLI) |