Favicon Generator

Critical path

The bundled CLI lives inside this skill folder. Do not look for scripts/image_gen.py in the project root.

Resolve the CLI path first:

if [ -f ".agents/skills/favicon-generator/scripts/image_gen.py" ]; then
  ICON_CLI=".agents/skills/favicon-generator/scripts/image_gen.py"
elif [ -f "$HOME/.agents/skills/favicon-generator/scripts/image_gen.py" ]; then
  ICON_CLI="$HOME/.agents/skills/favicon-generator/scripts/image_gen.py"
else
  echo "favicon-generator CLI not found" >&2
  exit 1
fi

Safe preflight (run before generation)

python3 "$ICON_CLI" generate --prompt "test icon" --dry-run

The CLI output will report whether OPENAI_API_KEY is set after auto-loading env files.

Check DNS before live API calls:

python3 - <<'PY'
import socket
socket.gethostbyname("api.openai.com")
print("DNS ok: api.openai.com")
PY

If DNS lookup fails, do not attempt a live generate call in that environment.

Dependency check

python3 - <<'PY'
import importlib.util
print('openai', bool(importlib.util.find_spec('openai')))
print('PIL', bool(importlib.util.find_spec('PIL')))
PY

If missing, run exactly one deterministic install path:

python3 -m pip install --user openai pillow

If Python is externally managed (PEP-668), use a local venv and continue there. Do not thrash between multiple install strategies.

Prompt crafting guidelines

The API model (gpt-image-1.5) has specific strengths and limitations that affect icon quality:

• Text rendering is unreliable — always include "no text, no lettering" in constraints.
• Composition control is limited — keep the concept to a single centered element. Do not ask for multiple objects or complex layouts.
• The model follows color instructions well — use exact hex values from the project's manifest.ts (theme_color, background_color).
• Fine detail disappears at small sizes — the generated 1024x1024 master gets scaled down to 16x16 for favicon.ico and 72x72 for badge. Avoid thin strokes, fine lines, or intricate patterns.

Prompt structure (for --prompt)

Use short labeled lines, not a long paragraph:

Primary request: <what the icon depicts — keep it to one simple concept>
Style/medium: flat vector icon mark; clean geometric shapes; minimal
Composition/framing: single centered symbol with generous padding; all critical elements within center 80% safe zone
Color palette: <symbol color hex> on <background color hex>; high contrast
Subject: <concrete visual description — e.g. "interlocking angular shapes" not "speed and modularity">

Default constraints (for --constraints)

single centered app icon mark, no text, no lettering, no watermark, no gradients, opaque solid background, high contrast, clean shape language, strong silhouette readable at 16px, all critical elements within center 80% safe zone for maskable icon cropping, no fine lines or thin strokes that disappear at small sizes

What to avoid in prompts

• Vibe-only buzzwords: "epic", "cinematic", "trending", "8K", "award-winning"
• Abstract concepts the model can't visualize: "speed", "progressive", "modularity"
• Multiple subjects or complex scenes
• Gradients (break at small sizes and complicate maskable icon backgrounds)
• Any text or lettering (will render poorly and become illegible at favicon sizes)

Workflow A: generate new icon from prompt

1. Generate a 1024x1024 master icon in one command (env + call together):

mkdir -p tmp/favicon-generator
python3 "$ICON_CLI" generate --prompt "<USER_PROMPT>" --size 1024x1024 --quality high --output-format png --out tmp/favicon-generator/app-icon-master.png --use-case logo-brand --constraints "single centered app icon mark, no text, no lettering, no watermark, no gradients, opaque solid background, high contrast, clean shape language, strong silhouette readable at 16px, all critical elements within center 80% safe zone for maskable icon cropping, no fine lines or thin strokes that disappear at small sizes" --force

2. Export required PWA sizes:

mkdir -p public tmp/favicon-generator
cp tmp/favicon-generator/app-icon-master.png public/icon-512x512.png
sips -s format png public/icon-512x512.png --resampleHeightWidth 192 192 --out public/icon-192x192.png >/dev/null
sips -s format png public/icon-512x512.png --resampleHeightWidth 180 180 --out public/apple-touch-icon.png >/dev/null
sips -s format png public/icon-512x512.png --resampleHeightWidth 72 72 --out public/badge-72x72.png >/dev/null
sips -s format png public/icon-512x512.png --resampleHeightWidth 512 512 --out public/icon-maskable-512x512.png >/dev/null
sips -s format png public/icon-512x512.png --resampleHeightWidth 192 192 --out public/icon-maskable-192x192.png >/dev/null
python3 - <<'PY'
from PIL import Image
img = Image.open("public/icon-512x512.png").convert("RGBA")
img.save("app/favicon.ico", format="ICO", sizes=[(16, 16), (32, 32), (48, 48), (64, 64)])
print("Wrote app/favicon.ico")
PY

3. Verify outputs:

ls -la public/icon-512x512.png public/icon-192x192.png public/icon-maskable-512x512.png public/icon-maskable-192x192.png public/apple-touch-icon.png public/badge-72x72.png app/favicon.ico

Workflow B: start from existing source image

If the user already has a source icon, skip generation and export from it:

SOURCE="path/to/source-icon.png"
mkdir -p public
cp "$SOURCE" public/icon-512x512.png
sips -s format png public/icon-512x512.png --resampleHeightWidth 192 192 --out public/icon-192x192.png >/dev/null
sips -s format png public/icon-512x512.png --resampleHeightWidth 180 180 --out public/apple-touch-icon.png >/dev/null
sips -s format png public/icon-512x512.png --resampleHeightWidth 72 72 --out public/badge-72x72.png >/dev/null
sips -s format png public/icon-512x512.png --resampleHeightWidth 512 512 --out public/icon-maskable-512x512.png >/dev/null
sips -s format png public/icon-512x512.png --resampleHeightWidth 192 192 --out public/icon-maskable-192x192.png >/dev/null
python3 - <<'PY'
from PIL import Image
img = Image.open("public/icon-512x512.png").convert("RGBA")
img.save("app/favicon.ico", format="ICO", sizes=[(16, 16), (32, 32), (48, 48), (64, 64)])
print("Wrote app/favicon.ico")
PY

Troubleshooting

• Missing API key:
  • Ensure .env.local (or .env) in repo root contains OPENAI_API_KEY=....
• Missing Python deps:
  • python3 -m pip install --user openai pillow
  • If system Python is externally managed (PEP-668), use a local venv.
• sips ICO conversion failure (Error 13):
  • Use Pillow for app/favicon.ico generation (already shown in workflows).
• Network/DNS failure during API call:
  • Prefer DNS precheck before API call to avoid wasting attempts.
  • Report failure clearly and stop after that attempt.
  • Provide the exact same generation command for user to run in a network-enabled shell.
  • Offer Workflow B (export from existing source image) to unblock immediately.

Execution notes

• Keep temp files under tmp/favicon-generator/.
• Keep final artifacts in standard project icon locations listed above.
• For status/notes updates, prefer direct file edits over fragile quoted printf shell snippets.