Fal Skill Creator

fal.ai Skill Creator

Generate reusable Claude Code Skills from fal.ai model IDs using the Platform API.

Authentication

All fal.ai operations require the FAL_KEY environment variable:

export FAL_KEY="your-fal-api-key"

File Upload (for image/audio/video inputs)

Many models require URL inputs for media files. Use fal_client to upload local files:

# Upload file and get URL
python -c "import fal_client; url=fal_client.upload_file(r'/path/to/file.png'); print(f'URL: {url}')"

# Linux/Mac
python -c "import fal_client; url=fal_client.upload_file('/home/user/image.png'); print(f'URL: {url}')"

# Android (Termux)
python -c "import fal_client; url=fal_client.upload_file('/storage/emulated/0/Download/image.png'); print(f'URL: {url}')"

Supported formats: png, jpg, gif, webp, mp3, wav, mp4, webm, etc.

Quick Start

Generate Skill from Model ID

# Generate skill for a model
python .claude/skills/fal-skill-creator/scripts/generate_fal_skill.py \
  --model-id fal-ai/flux/dev

# Lazy mode (minimal SKILL.md, details in YAML)
python .claude/skills/fal-skill-creator/scripts/generate_fal_skill.py \
  --model-id fal-ai/flux/dev --lazy

# Standalone mode (copy shared scripts instead of symlinks)
python .claude/skills/fal-skill-creator/scripts/generate_fal_skill.py \
  --model-id fal-ai/flux/dev --standalone

# Public mode (implies --standalone and validates skill tree has no symlinks)
python .claude/skills/fal-skill-creator/scripts/generate_fal_skill.py \
  --model-id fal-ai/flux/dev --public

# Multiple models
python .claude/skills/fal-skill-creator/scripts/generate_fal_skill.py \
  --model-id fal-ai/flux/dev \
  --model-id fal-ai/flux/schnell

Output: .claude/skills/<model-name>/

Search for Models

python .claude/skills/fal-skill-creator/scripts/generate_fal_skill.py \
  --search "flux" --category "text-to-image"

Direct API Call

python .claude/skills/fal-skill-creator/scripts/fal_api_call.py \
  --model-id fal-ai/flux/schnell \
  --args '{"prompt": "a cat in a garden"}' \
  --output ./output

Using Generated Skills

After generation, use the wrapper script:

python .claude/skills/fal-ai-flux-dev/scripts/fal_ai_flux_dev.py \
  --args '{"prompt": "sunset over mountains"}' \
  --output ./output

CLI Reference

generate_fal_skill.py

fal_api_call.py

Download size limit: 100MB per file.

Queue Management

# Start daemon
python .claude/skills/fal-skill-creator/scripts/queue_daemon.py --background

# Check status
python .claude/skills/fal-skill-creator/scripts/queue_client.py --status

# Shutdown
python .claude/skills/fal-skill-creator/scripts/queue_client.py --shutdown

Generated Skill Structure

.claude/skills/<model-name>/
├── SKILL.md
├── queue_config.yaml
├── agents/
│   └── openai.yaml           # UI metadata (display_name / prompt)
├── scripts/
│   ├── fal_api_call.py       # default: symlink / --standalone: copy
│   ├── queue_client.py       # default: symlink / --standalone: copy
│   ├── queue_protocol.py     # default: symlink / --standalone: copy
│   ├── queue_daemon.py       # default: symlink / --standalone: copy
│   └── <model_name>.py       # Wrapper with MODEL_ID preset
└── references/
    ├── model_config.json      # {model_id, name, category, description}
    └── tools/                 # lazy mode only
        └── <model-name>.yaml  # Input/output schema + usage examples

fal.ai Queue API Flow

1. SUBMIT    → POST queue.fal.run/{model_id}     → Get request_id
2. STATUS    → GET .../requests/{id}/status       → Wait for COMPLETED
3. RESULT    → GET .../requests/{id}              → Get output URLs
4. DOWNLOAD  → Save files locally

Status values: IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED

Recovery behavior:

• If submit returns timeout/network error or HTTP 405, attempt request recovery via Platform API (/v1/models/requests/by-endpoint) and continue with recovered request_id.
• If queue result endpoints return 405 after submit, do not auto-fallback to sync (duplicate billing risk). Return metadata-only result with status=RESULT_ENDPOINT_ONLY and platform_request when possible.

Queue Daemon Configuration (queue_config.yaml)

Environment variable overrides: FAL_QUEUE_MAX_CONCURRENT, FAL_QUEUE_RATE_PER_MIN, FAL_QUEUE_CLIENT_IDLE_TIMEOUT, etc.

Security: queue daemon enforces runtime dir ownership/permissions (0700) and only removes stale socket paths when the existing path is a socket/symlink.

Runtime scope:

• Generated wrappers isolate runtime dirs per skill/model (~/.cache/fal-queue/<skill>__<model>__v2), so concurrency/rate limits apply per skill-model daemon.
• Queue client restarts stale daemons when local scripts/config are newer than the daemon start marker (PID file mtime), reducing mixed old/new behavior risks.

Programmatic Usage

import sys, os
sys.path.insert(0, os.path.join(".claude", "skills", "fal-skill-creator", "scripts"))
from fal_api_call import run_fal_api_job

result = run_fal_api_job(
    model_id="fal-ai/flux/schnell",
    submit_args={"prompt": "a cat in a garden"},
    output_dir="./output",
)
print(result.get("saved_path") or result)

Error Handling

• API errors (4xx/5xx) with automatic retry on transient errors (429, 5xx)
• Job failures (FAILED status) with descriptive messages
• Timeout after max polls
• Download failures
• Queue daemon connection failures with fallback to direct API
• On submit timeout/network/405, recover request_id from Platform API before deciding fallback
• If queue submit succeeds but queue endpoints return 405, sync fallback is blocked to prevent duplicate execution/billing
• If queue result endpoints remain unavailable, return RESULT_ENDPOINT_ONLY with platform_request metadata (no automatic retry)

All errors raise exceptions with descriptive messages.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.