Agent Skills

1---
2name: "sora"
3description: "Use when the user asks to generate, remix, poll, list, download, or delete Sora videos via OpenAI\u2019s video API using the bundled CLI (`scripts/sora.py`), including requests like \u201cgenerate AI video,\u201d \u201cSora,\u201d \u201cvideo remix,\u201d \u201cdownload video/thumbnail/spritesheet,\u201d and batch video generation; requires `OPENAI_API_KEY` and Sora API access."
4---
5 
6 
7# Sora Video Generation Skill
8 
9Creates or manages short video clips for the current project (product demos, marketing spots, cinematic shots, UI mocks). Defaults to `sora-2` and a structured prompt augmentation workflow, and prefers the bundled CLI for deterministic runs. Note: `$sora` is a skill tag in prompts, not a shell command.
10 
11## When to use
12- Generate a new video clip from a prompt
13- Remix an existing video by ID
14- Poll status, list jobs, or download assets (video/thumbnail/spritesheet)
15- Batch runs (many prompts or variants)
16 
17## Decision tree (create vs remix vs status/download vs batch)
18- If the user has a **video id** and wants a change → **remix**
19- If the user has a **video id** and wants status or assets → **status/poll/download**
20- If the user needs many prompts/assets → **create-batch**
21- If the user asks for two versions with a small change (same shot, different subject/detail) → **create** the base, then **remix** for the variation
22- Otherwise → **create** (or **create-and-poll** if they need a ready asset in one step)
23 
24## Workflow
251. Decide intent: create vs remix vs status/download vs batch.
262. Collect inputs: prompt, model, size, seconds, and any input reference image.
273. If batch: write a temporary JSONL under tmp/ (one job per line), run once, then delete the JSONL.
284. Prefer CLI augmentation flags (`--use-case`, `--scene`, `--camera`, etc.) instead of pre-writing a structured prompt. If you already produced a structured prompt file, pass `--no-augment` to avoid double-wrapping.
295. Run the bundled CLI (`scripts/sora.py`) with sensible defaults (see references/cli.md). For long prompts, prefer `--prompt-file` to avoid shell-escaping issues; pair with `--no-augment` if the prompt is already structured.
306. For async jobs, poll until complete (or use create-and-poll).
317. Download assets (video/thumbnail/spritesheet) and save locally.
328. Remove intermediate files created during invocation (for example `prompt.txt`, `remix_job.json`, temp JSONL). If the sandbox blocks `rm`, skip cleanup or truncate the files without surfacing an error.
339. Iterate with a single targeted change per prompt.
34 
35## Authentication
36- `OPENAI_API_KEY` must be set for live API calls.
37 
38If the key is missing, give the user these steps:
391. Create an API key in the OpenAI platform UI: https://platform.openai.com/api-keys
402. Set `OPENAI_API_KEY` as an environment variable in their system.
413. Offer to guide them through setting the environment variable for their OS/shell if needed.
42- Never ask the user to paste the full key in chat. Ask them to set it locally and confirm when ready.
43 
44## Defaults & rules
45- Default model: `sora-2` (use `sora-2-pro` for higher fidelity).
46- Default size: `1280x720`.
47- Default seconds: `4` (allowed: "4", "8", "12" as strings).
48- Always set size and seconds via API params; prose will not change them.
49- Use the OpenAI Python SDK (`openai` package); do not use raw HTTP.
50- Require `OPENAI_API_KEY` before any live API call.
51- If uv cache permissions fail, set `UV_CACHE_DIR=/tmp/uv-cache`.
52- Input reference images must be jpg/png/webp and should match target size.
53- Download URLs expire after about 1 hour; copy assets to your own storage.
54- Prefer the bundled CLI and **never modify** `scripts/sora.py` unless the user asks.
55- Sora can generate audio; if a user requests voiceover/audio, specify it explicitly in the `Audio:` and `Dialogue:` lines and keep it short.
56 
57## API limitations
58- Models are limited to `sora-2` and `sora-2-pro`.
59- API access to Sora models requires an organization-verified account.
60- Duration is limited to 4/8/12 seconds and must be set via the `seconds` parameter.
61- The API expects `seconds` as a string enum ("4", "8", "12").
62- Output sizes are limited by model (see `references/video-api.md` for the supported sizes).
63- Video creation is async; you must poll for completion before downloading.
64- Rate limits apply by usage tier (do not list specific limits).
65- Content restrictions are enforced by the API (see Guardrails below).
66 
67## Guardrails (must enforce)
68- Only content suitable for audiences under 18.
69- No copyrighted characters or copyrighted music.
70- No real people (including public figures).
71- Input images with human faces are rejected.
72 
73## Prompt augmentation
74Reformat prompts into a structured, production-oriented spec. Only make implicit details explicit; do not invent new creative requirements.
75 
76Template (include only relevant lines):
77```
78Use case: <where the clip will be used>
79Primary request: <user's main prompt>
80Scene/background: <location, time of day, atmosphere>
81Subject: <main subject>
82Action: <single clear action>
83Camera: <shot type, angle, motion>
84Lighting/mood: <lighting + mood>
85Color palette: <3-5 color anchors>
86Style/format: <film/animation/format cues>
87Timing/beats: <counts or beats>
88Audio: <ambient cue / music / voiceover if requested>
89Text (verbatim): "<exact text>"
90Dialogue:
91<dialogue>
92- Speaker: "Short line."
93</dialogue>
94Constraints: <must keep/must avoid>
95Avoid: <negative constraints>
96```
97 
98Augmentation rules:
99- Keep it short; add only details the user already implied or provided elsewhere.
100- For remixes, explicitly list invariants ("same shot, change only X").
101- If any critical detail is missing and blocks success, ask a question; otherwise proceed.
102- If you pass a structured prompt file to the CLI, add `--no-augment` to avoid the tool re-wrapping it.
103 
104## Examples
105 
106### Generation example (single shot)
107```
108Use case: product teaser
109Primary request: a close-up of a matte black camera on a pedestal
110Action: slow 30-degree orbit over 4 seconds
111Camera: 85mm, shallow depth of field, gentle handheld drift
112Lighting/mood: soft key light, subtle rim, premium studio feel
113Constraints: no logos, no text
114```
115 
116### Remix example (invariants)
117```
118Primary request: same shot and framing, switch palette to teal/sand/rust with warmer backlight
119Constraints: keep the subject and camera move unchanged
120```
121 
122## Prompting best practices (short list)
123- One main action + one camera move per shot.
124- Use counts or beats for timing ("two steps, pause, turn").
125- Keep text short and the camera locked-off for UI or on-screen text.
126- Add a brief avoid line when artifacts appear (flicker, jitter, fast motion).
127- Shorter prompts are more creative; longer prompts are more controlled.
128- Put dialogue in a dedicated block; keep lines short for 4-8s clips.
129- State invariants explicitly for remixes (same shot, same camera move).
130- Iterate with single-change follow-ups to preserve continuity.
131 
132## Guidance by asset type
133Use these modules when the request is for a specific artifact. They provide targeted templates and defaults.
134- Cinematic shots: `references/cinematic-shots.md`
135- Social ads: `references/social-ads.md`
136 
137## CLI + environment notes
138- CLI commands + examples: `references/cli.md`
139- API parameter quick reference: `references/video-api.md`
140- Prompting guidance: `references/prompting.md`
141- Sample prompts: `references/sample-prompts.md`
142- Troubleshooting: `references/troubleshooting.md`
143- Network/sandbox tips: `references/codex-network.md`
144 
145## Reference map
146- **`references/cli.md`**: how to run create/poll/remix/download/batch via `scripts/sora.py`.
147- **`references/video-api.md`**: API-level knobs (models, sizes, duration, variants, status).
148- **`references/prompting.md`**: prompt structure and iteration guidance.
149- **`references/sample-prompts.md`**: copy/paste prompt recipes (examples only; no extra theory).
150- **`references/cinematic-shots.md`**: templates for filmic shots.
151- **`references/social-ads.md`**: templates for short social ad beats.
152- **`references/troubleshooting.md`**: common errors and fixes.
153- **`references/codex-network.md`**: network/approval troubleshooting.
154