# Claude Code Desktop skills for image and text to video

Research date: 25 April 2026  
Audience: non-coders setting up a repeatable creative generation workflow  
Scope: Claude Code inside the Claude Desktop app, using skills to run a saved process end to end, with fal.ai as the generation service

## The simple version

Claude Code Desktop gives you a visual way to run Claude Code inside the Claude Desktop app. You work inside the Code tab, choose a project folder, choose where Claude runs, choose a model and choose how much permission Claude has.

A skill is a saved instruction file called `SKILL.md`. You can run it by typing its slash command, such as `/fal-video-pipeline`. Claude can also choose to load a skill automatically, but for generation workflows with side effects you should make the skill manual only.

For your use case, the clean setup is:

1. A project folder for the pipeline.
2. A skill that explains the workflow.
3. A runner script that calls fal.ai.
4. A prompt file with multiple rows or objects.
5. An output folder where generated videos, logs and metadata are saved.

Claude should orchestrate the process. The runner script should do the repeatable work.

## What Claude Code Desktop can do

Claude Code Desktop is the Code tab inside the Claude Desktop app. It lets you use Claude Code through a graphical interface instead of only using the terminal.

Useful Desktop features for this workflow:

| Feature | Why it matters for a fal.ai video pipeline |
| --- | --- |
| Code tab | Run a Claude Code session from a visual interface. |
| Project folder | Give Claude access to the folder containing prompts, scripts and outputs. |
| Local environment | Run on your own Mac or PC, with access to local files and installed tools. |
| Remote environment | Run on Anthropic cloud infrastructure. Useful for long jobs, but it works from a fresh clone rather than your local checkout. |
| Permission modes | Start cautiously, then reduce prompts once the workflow is trusted. |
| Integrated terminal | Run setup commands and test scripts without switching apps. Available in local sessions. |
| File editor and diff view | Review files Claude creates or edits. |
| Preview pane | Preview HTML, PDFs, images and app output. |
| Parallel sessions | Run separate attempts or tests without mixing changes. Git projects get isolated worktrees. |
| Side chats | Ask questions about the setup without derailing the main run. |
| Scheduled tasks | Optional. Not needed for your definition of automation, but available if you later want a saved task you can click or schedule. |

## What a skill is

A skill is a folder with a required `SKILL.md` file.

Example personal skill location:

```text
~/.claude/skills/fal-video-pipeline/SKILL.md
```

Example project skill location:

```text
your-project/
  .claude/
    skills/
      fal-video-pipeline/
        SKILL.md
```

Use a personal skill when you want it available across all projects. Use a project skill when it belongs to one repo or one pipeline folder.

A skill can also include supporting files:

```text
fal-video-pipeline/
  SKILL.md
  reference.md
  examples.md
  scripts/
    run-video-batch.js
    validate-inputs.js
```

Keep `SKILL.md` focused. Put detailed API notes, examples and scripts in separate files.

## When to use a skill

Use a skill when you keep repeating the same process.

Good skill candidates:

| Workflow | Skill fit |
| --- | --- |
| Generate videos from a list of prompts | Yes |
| Turn start frames into image to video clips | Yes |
| Validate prompt files before generation | Yes |
| Download and organise fal outputs | Yes |
| Rename files and write a run report | Yes |
| Pick one random creative idea | Not really |
| Ask for general advice | Not really |

A skill is not magic automation by itself. It is a reusable playbook Claude can follow. For a reliable video pipeline, the skill should call a script.

## Recommended setup for your fal.ai video skill

Use this structure:

```text
video-pipeline/
  .claude/
    skills/
      fal-video-pipeline/
        SKILL.md
        reference.md
        examples.md
  inputs/
    prompts.json
    start-frames/
  scripts/
    run-video-batch.js
  outputs/
    .gitkeep
  package.json
  README.md
```

What each part does:

| File or folder | Purpose |
| --- | --- |
| `.claude/skills/fal-video-pipeline/SKILL.md` | The saved Claude Code workflow. |
| `inputs/prompts.json` | The list of prompts, image references, model IDs and settings. |
| `inputs/start-frames/` | Local images used for image to video. |
| `scripts/run-video-batch.js` | The script that calls fal.ai and saves outputs. |
| `outputs/` | Final videos, logs and metadata. |
| `package.json` | Project setup and dependency list. |
| `README.md` | Human instructions for the project. |

## How to set up Claude Desktop

1. Install Claude Desktop for macOS or Windows.
2. Open Claude Desktop.
3. Sign in.
4. Click the Code tab.
5. Check for updates before relying on Desktop features.
6. Start a new Code session.
7. Choose Local as the environment for early testing.
8. Choose your pipeline folder as the project folder.
9. Choose a model.
10. Start in Ask permissions or Plan mode.
11. Move to Auto accept edits only after the skill is working.

Use Local for the first version because it can see your local files, use your installed tools and access your output folder directly.

Use Remote later if you want long runs to continue when the app is closed. For Remote, commit the project files to a repository, configure the cloud environment and add `FAL_KEY` there.

## Set up fal.ai access

The safe pattern is:

1. Create a fal.ai account.
2. Create an API key in fal.ai.
3. Store it as an environment variable called `FAL_KEY`.
4. Do not paste the key into `SKILL.md`.
5. Do not put the key in a browser app.
6. Do not commit the key to Git.

For a local Claude Code Desktop session, set `FAL_KEY` in the Local environment editor. The Desktop app does not always inherit every variable from your normal shell, so setting it inside Desktop is the safer path.

For a server side script, fal.ai clients can read `FAL_KEY` from the environment.

## Pick the fal.ai calling method

fal.ai has several ways to call models. For this pipeline, the two useful ones are `subscribe` and `submit`.

| Method | Plain English | Best for |
| --- | --- | --- |
| `subscribe` | Submit the job and wait until it finishes. The client polls for you. | Simple scripts and early testing. |
| `submit` | Submit the job, keep the request ID, then check status or fetch the result later. | Multiple prompts, longer jobs and better tracking. |

For a batch video pipeline, use `submit` once the workflow is stable. It lets you launch multiple requests, store request IDs and recover if something fails.

For a very simple first version, `subscribe` is fine.

## Use exact model schemas

fal.ai model inputs and outputs are model specific. Do not guess the fields.

For every model you use:

1. Open the fal.ai model page.
2. Use the Playground to test a prompt.
3. Copy the working API example.
4. Copy the exact input fields into your runner script.
5. Save the model ID in your prompt file.
6. Save the returned request ID and output URL in your metadata.

Video models usually return a `video` object, but you should still check the model page for the exact output shape.

## Suggested prompt file shape

Use JSON because it is easy for scripts and Claude to read.

```json
{
  "run_name": "test-run-001",
  "defaults": {
    "aspect_ratio": "16:9",
    "duration": "5"
  },
  "jobs": [
    {
      "id": "shot-001",
      "mode": "text-to-video",
      "model": "MODEL_ID_FROM_FAL",
      "prompt": "A cinematic product shot of...",
      "settings": {}
    },
    {
      "id": "shot-002",
      "mode": "image-to-video",
      "model": "MODEL_ID_FROM_FAL",
      "image_path": "inputs/start-frames/shot-002.png",
      "prompt": "Slow dolly in, subtle atmospheric movement...",
      "settings": {}
    }
  ]
}
```

Keep the prompt file model agnostic. The runner script should translate each job into the exact input shape required by the selected fal.ai model.

## What the runner script should do

The runner script is the reliable part of the system.

It should:

1. Read `inputs/prompts.json`.
2. Check every job has an `id`, `mode`, `model` and `prompt`.
3. Check local image files exist for image to video jobs.
4. Read `FAL_KEY` from the environment.
5. Submit each job to fal.ai.
6. Log request IDs.
7. Track status.
8. Fetch final results.
9. Download videos to `outputs/<run-name>/videos/`.
10. Save a machine-readable log to `outputs/<run-name>/run-log.json`.
11. Save a human-readable report to `outputs/<run-name>/report.md`.
12. Mark failed jobs without stopping the whole batch.
13. Never expose the API key in logs.

Good output structure:

```text
outputs/
  test-run-001/
    videos/
      shot-001.mp4
      shot-002.mp4
    metadata/
      shot-001.json
      shot-002.json
    run-log.json
    report.md
```

Download the media files you want to keep. fal.ai media URLs are public and subject to media expiration settings.

## Starter skill shape

This is a safe starting shape, not the final pipeline.

```markdown
---
name: fal-video-pipeline
description: Run the local fal.ai image and text to video pipeline from a prompt file, save videos, metadata and a report.
disable-model-invocation: true
argument-hint: [path-to-prompts-json]
allowed-tools:
  - Read
  - Write
  - Bash(node *)
  - Bash(pnpm *)
  - Bash(mkdir *)
  - Bash(cat *)
---

# fal video pipeline

Run this skill only when the user explicitly asks for the fal video pipeline.

## Input

Use `$ARGUMENTS` as the prompt file path. If no argument is supplied, use `inputs/prompts.json`.

## Steps

1. Confirm the project has a script at `scripts/run-video-batch.js`.
2. Confirm the prompt file exists.
3. Confirm `FAL_KEY` is available in the environment without printing it.
4. Run the batch script from the project root.
5. Save all outputs inside `outputs/`.
6. Report:
   - where the videos were saved
   - which jobs succeeded
   - which jobs failed
   - any request IDs or error messages needed for debugging
7. Do not paste the API key into chat, files or logs.
```

Why this shape works:

| Choice | Reason |
| --- | --- |
| `disable-model-invocation: true` | Claude will not start generating videos just because the topic comes up. You run it manually. |
| `argument-hint` | The slash command shows what input it expects. |
| `allowed-tools` | Reduces permission prompts for known safe tools while the skill is active. |
| Script based run | Makes the workflow repeatable. |
| Output report | Gives a readable result after each batch. |

## How to run the skill

Inside the Claude Desktop Code tab:

```text
/fal-video-pipeline inputs/prompts.json
```

During early testing:

1. Use a tiny prompt file with one text to video job.
2. Run in Ask permissions.
3. Approve only the commands you understand.
4. Check the output folder.
5. Check `run-log.json`.
6. Add one image to video job.
7. Test again.
8. Add more prompts once the first two jobs work.

Once trusted, you can reduce friction by saving approvals for the specific tools the skill needs.

## Permission notes

Permission modes control how much Claude can do without asking.

Start with:

| Mode | Use it when |
| --- | --- |
| Plan mode | You want Claude to inspect the setup and propose steps before editing or running anything. |
| Ask permissions | You are testing the skill and want to approve each action. |

Move later to:

| Mode | Use it when |
| --- | --- |
| Auto accept edits | You trust file edits, but still want prompts for most commands. |
| Auto | You want fewer prompts and are comfortable with Claude running more of the workflow. |

Avoid bypass permissions unless you are in a sandboxed folder or virtual machine. Generation workflows touch local files, API keys and paid API usage, so keep the boundary tight.

`allowed-tools` makes listed tools easier to run while the skill is active. It does not block every other tool. Use permission deny rules if you need hard blocks.

## Local or remote

Use Local when:

1. You are testing.
2. Your start frames are on your machine.
3. You want the output videos saved directly to your Mac or PC.
4. You need the integrated terminal.
5. You want the least setup.

Use Remote when:

1. The workflow files are committed to a repo.
2. The job may run for a long time.
3. You want it to continue when the app is closed.
4. You have configured the cloud environment and secrets.
5. You do not need uncommitted local files.

A remote session works from a fresh clone, so local-only images and uncommitted files will not be there unless you add them to the repo or upload them another way.

## Skills versus MCP versus hooks

For this pipeline, start with a skill plus script.

| Feature | Use it for this project |
| --- | --- |
| Skill | The main saved workflow you run manually. |
| Script | The repeatable fal.ai calls, downloads and logs. |
| MCP | Optional later if you want Claude to talk to another service directly. Not required for fal.ai API calls. |
| Hooks | Optional later for strict behaviours, such as running validation after edits. Not needed for the first version. |
| Scheduled tasks | Optional later. Not needed if automation means manual end to end run. |

## Development checklist

Use this order.

1. Create the project folder.
2. Add `inputs/`, `scripts/`, `outputs/`.
3. Add a one-job `inputs/prompts.json`.
4. Install the fal client package.
5. Add `FAL_KEY` to the Claude Desktop Local environment editor.
6. Create `scripts/run-video-batch.js`.
7. Test the script directly once.
8. Create `.claude/skills/fal-video-pipeline/SKILL.md`.
9. Open Claude Desktop Code tab.
10. Choose Local.
11. Choose the project folder.
12. Run `/skills` to confirm the skill appears.
13. Run `/fal-video-pipeline inputs/prompts.json`.
14. Check `outputs/`.
15. Add image to video.
16. Add batching.
17. Add retry handling.
18. Add the final report format.

## A good first user prompt to Claude Code

Use this inside Claude Desktop Code, in your project folder:

```text
Create a local Claude Code skill called fal-video-pipeline for this project. The skill should be manually invoked only. It should run a local batch script that reads inputs/prompts.json, calls fal.ai using FAL_KEY from the environment, saves generated videos and metadata into outputs/<run-name>/, and writes a report.md. Start with one text-to-video job and one image-to-video job. Do not hardcode any API key. Use the exact model schemas from the fal.ai model pages after I choose the model IDs.
```

## What to avoid

Avoid these patterns:

| Avoid | Why |
| --- | --- |
| Putting `FAL_KEY` in `SKILL.md` | It can leak into files, history or logs. |
| Calling fal.ai from browser code with the raw key | Browser source is visible. |
| Letting Claude invent model fields | fal.ai schemas are model specific. |
| Running 50 prompts on the first test | Debugging becomes messy. |
| Only saving fal media URLs | Media URLs are public and can expire. |
| Relying on skill prose only | A script is more repeatable than natural language instructions. |
| Auto-running a generation skill | Paid API calls should be manually triggered. |

## Troubleshooting

| Problem | Likely cause | Fix |
| --- | --- | --- |
| The skill does not appear | Wrong folder path or Claude has not noticed the new top-level skills folder | Check the path, then restart Claude Code if the top-level skills folder was created after the session started. |
| Claude does not use the skill | The description is too vague, or the skill is manual only | Run it directly with `/fal-video-pipeline`. |
| Claude asks too many questions | Permission mode is cautious | Run once, approve safe tools and save approvals where appropriate. |
| `FAL_KEY` is missing | Desktop did not inherit your shell variable | Add it in the Local environment editor. |
| The script works in Terminal but not Desktop | Desktop environment differs from your shell | Set variables inside Desktop and check the integrated terminal. |
| Image to video fails | Image path is missing, unsupported, or not accessible in the current environment | Use local paths for Local sessions. Use committed or uploaded assets for Remote sessions. |
| Output URL works but file is not saved | The script only logged the URL | Add a download step to the runner. |
| Remote session cannot find local files | Remote uses a fresh clone | Commit required files or run locally. |
| Skill behaviour changed after long chat | Context may have compacted | Re-run the skill command. |

## Source baseline

This guide is based on the official Claude Code and fal.ai documentation available on 25 April 2026.

Primary Claude sources:

1. Claude Code overview  
   https://code.claude.com/docs/en/overview

2. Claude Code Desktop  
   https://code.claude.com/docs/en/desktop

3. Claude Code skills  
   https://code.claude.com/docs/en/skills

4. Claude Code scheduled tasks  
   https://code.claude.com/docs/en/desktop-scheduled-tasks

5. Claude Code commands  
   https://code.claude.com/docs/en/commands

6. Claude Code extension overview  
   https://code.claude.com/docs/en/features-overview

Primary fal.ai sources:

1. fal.ai model APIs overview  
   https://fal.ai/docs/documentation/model-apis/overview

2. fal.ai client setup  
   https://fal.ai/docs/documentation/model-apis/inference/client-setup

3. fal.ai inference methods  
   https://fal.ai/docs/documentation/model-apis/inference

4. fal.ai asynchronous inference  
   https://fal.ai/docs/documentation/model-apis/inference/queue

5. fal.ai JavaScript client  
   https://fal.ai/docs/api-reference/client-libraries/javascript

6. fal.ai video model reference index via llms.txt  
   https://fal.ai/docs/llms.txt