Skills

generate-story

Installation
SKILL.md

Generate Story (Codex)

Use this skill when the user wants a new bedtime story for James or wants to refresh media for an existing story.

Input contract

Expect some combination of:

  • A freeform story prompt or source material.
  • Zero or more reference image paths.
  • Optionally a target date (YYYY-MM-DD).
  • Optionally a story id when updating an existing record.

If the user provides a long synopsis, movie plot, or article-like background, treat it as inspiration only. Do not retell it beat-by-beat.

Output contract

Always return:

  • title
  • story_content
  • image_key
  • video_key
  • story_id

When relevant, also return the resolved date.

Required environment

Required env vars:

  • STORY_API_TOKEN
  • REPLICATE_API_TOKEN for default replicate media generation
  • OPENAI_API_KEY for openai-media, openai-image, or openai-video
    • OPENAI_BEDTIME_STORY_KEY is also accepted as a local alias by the bundled scripts
  • STORY_API_BASE_URL (optional, defaults to https://bedtimestories.bruce-hart.workers.dev)

The bundled scripts will also auto-load $HOME/.config/secrets/codex.env when these vars are not already exported.

For any Python step, activate the venv first:

source ~/scripts/.venv/bin/activate

Fast path

Prefer this path unless blocked:

  1. Preflight.
  2. Resolve the story date.
  3. Write title and story content.
  4. Save the content to a temp file.
  5. Run run-generate-story.py.

Use the manual image/video/upload steps only if the runner cannot satisfy the task.

Preflight

Run this first:

source ~/scripts/.venv/bin/activate
set -a
source "$HOME/.config/secrets/codex.env"
set +a
python -c 'import os; assert os.getenv("STORY_API_TOKEN"), "STORY_API_TOKEN missing"'
python -c 'import os; assert os.getenv("REPLICATE_API_TOKEN") or os.getenv("OPENAI_API_KEY") or os.getenv("OPENAI_BEDTIME_STORY_KEY"), "REPLICATE_API_TOKEN or OpenAI key missing"'
command -v ffmpeg >/dev/null
command -v curl >/dev/null

Step 0: Resolve story date

Use this order:

  1. If the user explicitly gives a date, use it.
  2. Else if an input folder name contains YYYY-MM-DD, use that.
  3. Else if an input markdown file name contains YYYY-MM-DD, use that.
  4. Else pick the next open date, starting with today in America/New_York.

Preferred helper:

source ~/scripts/.venv/bin/activate
python .codex/skills/generate-story/scripts/next-open-date.py

Relevant env vars:

  • STORY_API_TOKEN required
  • STORY_API_BASE_URL optional
  • STORY_CALENDAR_DAYS optional, default 365
  • STORY_TIMEZONE optional, default America/New_York

Step 1: Write the story

Write a bedtime story for James.

Hard requirements:

  • Return the title separately.
  • Do not include the title in story_content.
  • Use plain text paragraphs only.
  • No headings, bullets, or markdown decoration in the story body.
  • Default target length: 180-260 words.
  • Default target structure: 8-14 short paragraphs.
  • Use short, phonics-friendly sentences for a beginning reader.
  • End with a calm, safe feeling.

Source adaptation rules

If the user provides complex source material:

  • Extract only 1-3 child-friendly ideas.
  • Prefer one simple adventure or dream arc.
  • Do not reproduce the full plot.
  • Remove or soften death, murder, assassination, terror, political conflict, mind control, disaster, and other intense material unless the user clearly asks to keep it.
  • Bias toward wonder, helping, friendship, bravery, problem-solving, and a gentle ending.

Character rules

Only include people or pets that matter to the specific story.

Reference details:

  • James: seven years old, fair skin, short brown hair.
  • Mom: fair skin, shoulder-length brown hair with blonde highlights, glasses.
  • Dad: bald, clean shaven, brown hair, thick dark eyebrows.
  • Grace: four years old, long brown hair, fair skin.
  • Granny: short, short gray hair.
  • Grandma: short blonde hair, glasses.
  • Grandpa Bruce: bald, clean shaven.
  • Grandpa Rick: bald, clean shaven, glasses.
  • Trixie: small tuxedo cat with short legs, white paws, black chin, black face, white chest.

Media rules

Image requirements:

  • Landscape 16:9
  • Cartoon aesthetic
  • No text, letters, or signage
  • Only include characters relevant to the selected scene
  • If a named person appears, explicitly include that person's physical description from the Character rules in the image prompt
  • If the user specifies a visually distinctive setting, explicitly include those setting details in the image prompt

Video requirements:

  • Landscape 16:9
  • 5 seconds
  • Cartoon aesthetic
  • No text or letters
  • Use the generated image as the visual reference
  • Keep the action simple and readable
  • If a named person appears, explicitly include that person's physical description from the Character rules in the video prompt
  • Carry forward any user-specified distinctive setting details from the image prompt into the video prompt

Media prompt guidance

Keep prompts short and scene-specific.

Character fidelity requirements:

  • Do not refer to a named character only by role, such as Mom or Dad, when a physical description is available in Character rules
  • For each relevant named character in the scene, include the visible traits needed to identify them consistently
  • Include only the characters shown in the selected scene, but describe each of them concretely
  • If the setting has signature visual traits from the user prompt, include those traits explicitly rather than relying on the model to infer them

Image prompt template:

Landscape 16:9 cartoon bedtime scene. {scene}. Include only {relevant_characters_with_physical_descriptions}. Setting details: {visual_setting_details}. Warm storybook mood. No text, letters, or signage.

Video prompt template:

Gentle cartoon motion scene: {action}. Show {relevant_characters_with_physical_descriptions}. Setting details: {visual_setting_details}. Keep it cozy, readable, and simple. No text or letters.

Do not dump the whole story into the media prompt. Use one scene only.

Media providers

Default runner mode:

  • replicate uses Replicate for both image and video.

Optional runner modes:

  • --media-provider openai-media uses OpenAI for both steps.
  • --media-provider openai-image uses OpenAI for image and Replicate for video.
  • --media-provider openai-video uses Replicate for image and OpenAI for video.

Bundled OpenAI defaults:

  • Image: gpt-image-2, 1280x720, quality=low, output_format=jpeg
  • Video: sora-2, 1280x720, 4 seconds

Current OpenAI video caveat:

  • The OpenAI video docs say input_reference must match the target video size, and input images with human faces may be rejected. If openai-video or openai-media fails on a people-focused scene, retry with the default provider.

Preferred command: new story

After writing the story, save the body to a temp file such as /tmp/story.txt, then run:

source ~/scripts/.venv/bin/activate
python .codex/skills/generate-story/scripts/run-generate-story.py \
  --title "TITLE" \
  --content-file /tmp/story.txt \
  --date YYYY-MM-DD \
  --ref-image /path/to/reference-image

Useful flags:

  • --date YYYY-MM-DD to force a date
  • --ref-image /path/to.jpg repeatable
  • --media-provider replicate|openai-media|openai-image|openai-video to choose the media backend mix
  • --image-prompt "..." to override the default image prompt
  • --video-prompt "..." to override the default video prompt
  • --json for machine-readable output

Preferred command: update existing story media

Use this when the user wants to keep the story record but regenerate media:

source ~/scripts/.venv/bin/activate
python .codex/skills/generate-story/scripts/run-generate-story.py \
  --title "TITLE" \
  --content-file /tmp/story.txt \
  --story-id ID \
  --ref-image /path/to/reference-image

This regenerates media, uploads it, and updates image_url and video_url for the existing record.

Manual fallback

Use the manual path only if the runner is not suitable.

Generate image:

source ~/scripts/.venv/bin/activate
IMAGE_PATH=$(python .codex/skills/generate-story/scripts/generate-image.py \
  --image "/path/to/reference.jpg" \
  "IMAGE_PROMPT")

Add --provider openai to use gpt-image-2.

Generate video:

source ~/scripts/.venv/bin/activate
VIDEO_PATH=$(python .codex/skills/generate-story/scripts/generate-video.py \
  "$IMAGE_PATH" \
  "VIDEO_PROMPT")

Add --provider openai to use sora-2.

Re-encode for iPhone compatibility:

ffmpeg -y -i "$VIDEO_PATH" \
  -c:v libx264 -profile:v high -level 4.0 -pix_fmt yuv420p \
  -c:a aac -b:a 128k -movflags +faststart \
  /tmp/story-video-encoded.mp4

Upload media:

curl -s "${STORY_API_BASE_URL:-https://bedtimestories.bruce-hart.workers.dev}/api/media" \
  -H "X-Story-Token: $STORY_API_TOKEN" \
  -F "file=@/path/to/image.jpg"

curl -s "${STORY_API_BASE_URL:-https://bedtimestories.bruce-hart.workers.dev}/api/media" \
  -H "X-Story-Token: $STORY_API_TOKEN" \
  -F "file=@/tmp/story-video-encoded.mp4"

Create story:

curl -s "${STORY_API_BASE_URL:-https://bedtimestories.bruce-hart.workers.dev}/api/stories" \
  -H "X-Story-Token: $STORY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "TITLE",
    "content": "STORY_CONTENT",
    "date": "YYYY-MM-DD",
    "image_url": "IMAGE_KEY",
    "video_url": "VIDEO_KEY"
  }'

Final checklist

Before finishing, verify:

  • The story is short, simple, and bedtime-safe.
  • The title is separate from the body.
  • The body is plain text paragraphs only.
  • Only relevant characters appear in the story and media prompts.
  • Media prompts explicitly include the physical descriptions for every named person shown.
  • Media prompts include any distinctive user-requested setting details needed for scene accuracy.
  • Media prompts describe one scene, not the whole story.
  • The date is resolved.
  • The final response includes title, story content, image key, video key, and story id.
Installs
14
Repository
brucehart/codex-skills
GitHub Stars
1
First Seen
Feb 5, 2026
Security Audits
Gen Agent Trust HubPass