ImageForge

Use this skill to generate or edit raster images through the fixed NextAI Code image API.

First Execution Gate

On every ImageForge skill use, run ensure-ready as the first command:

WORKSPACE_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
IMAGE_FORGE_SCRIPT=""
for candidate in \
  "$WORKSPACE_ROOT/.agents/skills/image-forge/scripts/image_forge.py" \
  "$PWD/.agents/skills/image-forge/scripts/image_forge.py" \
  "$HOME/.agents/skills/image-forge/scripts/image_forge.py"; do
  if [ -f "$candidate" ]; then IMAGE_FORGE_SCRIPT="$candidate"; break; fi
done
if [ -z "$IMAGE_FORGE_SCRIPT" ]; then
  echo "ImageForge helper not found. Reinstall or update the image-forge skill."
  exit 2
fi
python3 "$IMAGE_FORGE_SCRIPT" ensure-ready

ensure-ready runs preflight. If configuration is missing, it stops the current flow, starts setup-server, waits for the user to save API key/model, then runs preflight again. Do not do any other work until preflight passes.

Image Brief Gate

After ensure-ready passes and before any image generation or editing command, Read references/image-brief.md.

You MUST complete the Image Brief Brainstorming Workflow before calling generate or edit. Maintain a visible checklist for the workflow. Do not compress the workflow into one brief. Do not answer the user's first normal image request with an Approved Image Brief, final prompt, or generation command.

Do not run generate or edit until the agent has explored context, asked clarifying questions one at a time, proposed 2-3 approaches, presented design sections, captured design confirmations, completed brief self-review, and the user approves the brief. Ask one question at a time and stop after the first question.

The helper enforces this gate: normal generation/editing must pass a structured --brief '<approved brief>' with question/answer evidence, 2-3 approaches, design confirmations, self-review, and explicit user approval. Hollow or one-line briefs are rejected before any provider call.

Direct mode: if the user explicitly says to generate/edit directly, not ask questions, or use the prompt exactly as written, skip clarification questions, briefly restate the execution understanding, then proceed with --direct. Do not use --direct unless the user explicitly asked to skip clarification.

Hard Rules

• Never store API keys in this skill folder, Git, logs, or replies.
• Prefer scripts/image_forge.py over hand-written HTTP commands.
• Use only the fixed NextAI Code API base: https://www.nextai-code.com/v1. Never use or suggest another API URL.
• Default model is gpt-image-2 unless the user configures another NextAI-supported model.
• Default output directory is the project root; write only .png image files and do not create output sidecar .json files.
• If preflight reports missing API key or model, start the local setup-server yourself; do not ask the user to run setup commands.
• Never continue with local layout, local drawing, screenshots, or any non-ImageForge fallback when ImageForge is unconfigured.
• Never turn a vague request into an API call without the Image Brief Gate unless Direct mode applies; the command must include either --brief '<approved brief>' or --direct.
• Editing must support one source image plus a text instruction; multi-image edit attempts must degrade clearly if the backend rejects them.
• Do not auto-upgrade the skill during image generation or editing.

Command Resolution

Use the IMAGE_FORGE_SCRIPT resolver above instead of hard-coding a single install directory. npx skills add may install to a workspace .agents/skills/image-forge directory, while other agents may install to $HOME/.agents/skills/image-forge.

Do not make normal users configure PATH. image-forge is only a convenience alias when already available; otherwise run python3 "$IMAGE_FORGE_SCRIPT" <command>.

Runtime Configuration

Configuration priority:

1. Fixed API URL: https://www.nextai-code.com/v1
2. IMAGE_FORGE_API_KEY, IMAGE_FORGE_MODEL
3. Project config at .image-forge/config.json for defaultModel and outputDir
4. User secret at ~/.config/image-forge/secrets.json for apiKey

IMAGE_FORGE_API_URL and .image-forge/config.json apiUrl are accepted only when they equal https://www.nextai-code.com or https://www.nextai-code.com/v1; any other URL is rejected before provider calls.

Configuration gate:

1. Resolve IMAGE_FORGE_SCRIPT.
2. Run:

python3 "$IMAGE_FORGE_SCRIPT" ensure-ready

3. If the browser does not open automatically, share the printed local URL with the user.
4. Wait for the user to submit API key and default model in the local page.
5. Continue only after ensure-ready returns ready.

The setup page listens on 127.0.0.1, uses a one-time token URL, never echoes the API key, shows the locked NextAI Code URL, links to https://www.nextai-code.com for registration/API key retrieval, persists configuration, and shuts down after saving.

Required readiness check:

python3 "$IMAGE_FORGE_SCRIPT" ensure-ready

If this command fails, do not continue the user's image task until configuration is complete.

Workflows

• First-use setup: agent runs python3 "$IMAGE_FORGE_SCRIPT" ensure-ready.
• CLI fallback setup: run python3 "$IMAGE_FORGE_SCRIPT" setup only if a browser form is unavailable; it prints the fixed NextAI Code URL and asks only for model/key.
• Setup server only: run python3 "$IMAGE_FORGE_SCRIPT" setup-server only for manual diagnostics.
• Preflight: run python3 "$IMAGE_FORGE_SCRIPT" preflight.
• Generate: after the Image Brief Gate, run python3 "$IMAGE_FORGE_SCRIPT" generate --brief '<approved brief>' --prompt '<approved prompt>'.
• Edit: after the Image Brief Gate, run python3 "$IMAGE_FORGE_SCRIPT" edit --brief '<approved brief>' --image '<path>' --prompt '<approved instruction>'.
• Diagnose: run python3 "$IMAGE_FORGE_SCRIPT" doctor.
• Version check: run python3 "$IMAGE_FORGE_SCRIPT" check-version.

References

• API details: references/openai-compatible-images.md (NextAI Code fixed-base edition)
• Image brief workflow: references/image-brief.md
• Installation: references/installation.md
• Troubleshooting: references/troubleshooting.md

Completion Report

Report the generated or edited image path, model, output size, and any degraded version-check or provider-compatibility status. Default outputs are written directly to the project root. Never report secrets.