/ray-so-code-snippet

name: ray-so-code-snippet
description: Generate beautiful code snippet images using ray.so. This skill should be used when the user asks to create a code image, code screenshot, code snippet image, or wants to make their code look pretty for sharing. Saves images locally to the current working directory or a user-specified path.

ray.so Code Snippet Image Generator

Generate beautiful code snippet images using [ray.so](https://ray.so/) and save them locally.

Requirements

• The user MUST provide the code snippet, either directly or by pointing to a file/selection in context
• MUST ask the user for ALL styling parameters before generating, presenting ALL available options
• MUST use `agent-browser` for screenshot capture (check availability first)

Workflow

Step 1: Verify agent-browser Availability

Before proceeding, verify that `agent-browser` is available:

which agent-browser

If `agent-browser` is not found in the PATH, inform the user that this skill requires agent-browser and cannot proceed without it.

Step 2: Fetch Available Options

Fetch the current themes and languages from ray.so's GitHub repository using curl:

# Fetch and parse available themes
curl -s "https://raw.githubusercontent.com/raycast/ray-so/main/app/(navigation)/(code)/store/themes.ts" | grep -oE 'id:\s*"[^"]+"' | sed 's/id:\s*"//;s/"//' | sort -u

# Fetch and parse available languages
curl -s "https://raw.githubusercontent.com/raycast/ray-so/main/app/(navigation)/(code)/util/languages.ts" | grep -oE '^[[:space:]]*"?[a-zA-Z0-9+#-]+"?\s*:\s*\{' | sed 's/[[:space:]]*"//g;s/".*//;s/:.*//' | sort -u

Step 3: Ask User for ALL Parameters

MUST use AskUserQuestion to ask for EVERY parameter, presenting ALL available options. Ask for parameters in this order:

3.1 Theme Selection

Present ALL available themes. In the question, list every theme fetched from step 2. Example:

Question: "Which theme would you like?"
Description: "Available themes: [list ALL themes from curl output]"
Options (pick 4 popular ones for quick select):
- breeze (default, purple gradient)
- midnight (cyan-blue)
- vercel (minimalist dark)
- sunset (warm orange)
Note: User can select "Other" to type any theme from the full list

3.2 Language Selection

**Infer the language when possible.** Skip this question if:

• The user explicitly specified a language
• The code comes from a file with a clear extension (e.g., `.py` → python, `.js` → javascript, `.ts` → typescript, `.rs` → rust, `.go` → go, etc.)
• The syntax is unmistakably identifiable (e.g., `def`/`import` → python, `func`/`package` → go, `fn`/`let mut` → rust)

Only ask this question if the language cannot be confidently inferred:

Question: "Which language for syntax highlighting?"
Description: "Available languages: [list ALL languages from curl output]"
Options:
- auto (auto-detect)
- javascript
- python
- typescript
Note: User can select "Other" to type any language from the full list

3.3 Dark/Light Mode

Question: "Dark or light mode?"
Options:
- Dark mode (default)
- Light mode

3.4 Background

Question: "Show the gradient background?"
Options:
- Yes, show background (default)
- No, transparent/minimal background

3.5 Padding

Question: "How much padding around the code?"
Options:
- 16 (compact)
- 32 (small)
- 64 (medium, default)
- 128 (large)

3.6 Line Numbers

Question: "Show line numbers?"
Options:
- No (default)
- Yes

3.7 Title

Question: "Add a title above the code? (e.g., filename)"
Options:
- No title (default)
- Yes, add title
If yes, ask for the title text.

Note: Do NOT ask about output path/filename. Save to the current working directory with a sensible filename (e.g., `rayso-snippet.png`, or based on the title if provided like `fibonacci.png`). Only use a different path if the user explicitly specifies one in their original request.

Step 4: Build the ray.so URL

**CRITICAL: ALL parameters must be in the URL hash (after #), NOT in the query string.**

Build the URL using shell commands:

# 1. Base64 encode the code
CODE_BASE64=$(echo -n 'YOUR_CODE_HERE' | base64)

# 2. URL encode the base64 string
CODE_ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$CODE_BASE64'))")

# 3. Build the URL with ALL parameters in the hash
# Format: https://ray.so/#param1=value1&param2=value2&code=ENCODED_CODE
# Do NOT include width parameter - let ray.so auto-size to fit content
URL="https://ray.so/#theme=THEME&padding=PADDING&background=BACKGROUND&darkMode=DARKMODE&language=LANGUAGE&code=${CODE_ENCODED}"

# Add optional parameters if needed:
# If lineNumbers: add "&lineNumbers=true" before &code=
# If title: add "&title=URL_ENCODED_TITLE" before &code=

**URL Hash Parameters:** | Parameter | Values | Default | |-----------|--------|---------| | theme | Any theme from list | breeze | | padding | 16, 32, 64, 128 | 64 | | background | true, false | true | | darkMode | true, false | true | | language | Any language from list, or "auto" | auto | | lineNumbers | true, false | false | | title | URL-encoded string | (none) | | width | Number (pixels) | auto | | code | Base64-encoded, then URL-encoded | (required) |

**Note on width:** Do NOT include the `width` parameter unless you specifically need a fixed width. Without it, ray.so auto-sizes the frame to fit the code content, avoiding unnecessary empty space.

**Example URL construction:**

# For code: for i in range(23):\n    print(i)
# Theme: midnight, Padding: 64, Dark mode: true, Background: true, Language: python, Title: test.py

CODE='for i in range(23):
    print(i)'
CODE_BASE64=$(echo -n "$CODE" | base64)
CODE_ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$CODE_BASE64'))")
TITLE_ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('test.py'))")
URL="https://ray.so/#theme=midnight&padding=64&background=true&darkMode=tru