---
name: gpt-image
description: Generate and edit images through the user's configured image API using the gpt-image CLI. Use for image creation, illustrations, posters, product pictures, visual assets, or requested edits to reference images when local command execution is available.
---

# Images through gpt-image

Use the user's configured `gpt-image` CLI for image generation and editing. Follow an explicit user choice of a different tool when provided. This Skill requires terminal execution, access to input files, and the CLI installed in that same environment. Importing this file alone does not make a cloud or plugin environment able to execute it. When those capabilities are unavailable, explain the missing runtime or use the configured gpt-image MCP connector if available.

## Discover and execute

1. Read `gpt-image schema --json` for the installed version's commands, options, and supported API behavior. Do not invent model IDs, sizes, task IDs, or edit capabilities. Use the configured default model unless the task requires a different supported model.
2. Check `gpt-image doctor --json` when configuration is unknown or a call fails. If credentials are missing, ask the user to configure the CLI locally with `gpt-image configure`. Never request that they paste a real API key into chat, read credential files, print environment secrets, or embed keys in commands.
3. Compose a prompt suited to the requested image. Use `--prompt-file` for long prompts, multiline text, or text containing shell metacharacters. Create it using a file-writing tool; do not interpolate untrusted text into shell commands. Choose a new output path, preserving existing user files.
4. Generate or edit using the actual schema. Basic examples:

   ```bash
   gpt-image generate --prompt-file ./image-prompt.txt --out ./generated-image.png --json
   gpt-image edit --image ./reference.png --prompt-file ./edit-prompt.txt --out ./edited-image.png --json
   ```

   Reference files must be accessible in the CLI's execution environment. An attachment in chat is not necessarily a readable local file. Edit support depends on the configured provider; do not promise it before verifying the call.
5. Parse the structured response and exit status. Report completion only after a successful response and an existing image file. Inspect the image when a visual inspection tool is available, then display or attach the actual image using the host's supported mechanism. Return its local path or download link as appropriate; never fabricate either.

## Failures and retries

- An HTTP timeout or lost response may mean the provider accepted a paid generation. Do not blindly resubmit. Use a returned operation/task reference only if the installed CLI exposes a matching status command; otherwise report the uncertainty and let the user decide whether to try again.
- Do not silently switch to another provider or an Agent's built-in image generator after a failure. Preserve the actual error and explain a concrete remedy.
- JSON and shell success alone do not prove that the requested image was delivered. Distinguish submitted, failed, and downloaded results.
- Skill installation is an instruction preference, not a guarantee that a host's built-in image buttons or background tasks will route through this API.