dotfiles/pi/.pi/agent/skills/visual-aid/SKILL.md

name, description

name	description
visual-aid	Delegate image understanding to a vision-capable subagent. Use when you need the contents of an image (screenshot, photo, diagram, chart, error dialog, UI mockup) but your model cannot see images: spawn the visual-aid agent with the image path(s) and a question, and it describes the image back to you in text.

Visual Aid — seeing images without vision

Your model cannot see images, but the visual-aid agent runs on a vision-capable model (qw/qwen3.8-max-preview) and can. Use it whenever a task requires knowing what is inside an image file.

When to use

• A user pasted or referenced an image (screenshot, photo, diagram, chart, error message, UI mockup) and you must act on its contents.
• You found image files while exploring (.png, .jpg, .jpeg, .gif, .webp, .bmp) whose content matters for the task.
• You need text read out of an image: error dialogs, terminal output in screenshots, labels, code in photos.

How to use

1. Locate the images with ls/find. Resolve relative paths to absolute paths.
2. Spawn the visual-aid agent with the Agent tool:

Agent tool call:
  subagent_type: "visual-aid"
  description: "Describe image for non-vision model"   # short, 3-5 words
  prompt: |
    Describe this image: /abs/path/to/image.png
    Question: <what you need to know>
    Context: <optional — e.g. "screenshot of a failed build", "photo of a whiteboard">

3. Do not override the model — visual-aid's vision model must be used. Only override with a model that supports image input.
4. Use the response: the returned text is your eyes. Quote it in your answer or act on it.

Passing multiple images

Pass every path in the prompt. Number them so the answers map to files:

Describe these images:
1. /abs/path/first.png — the error dialog
2. /abs/path/second.png — the terminal output
Question: What error is shown, and what does the terminal output say?

Prompting tips

• Always give the agent the specific question — "what does the error message say and which file does it reference?" beats "describe this image".
• Ask for verbatim text when text matters (error messages, code, labels): "quote all visible text exactly".
• Add context about the image's origin — it improves accuracy ("screenshot of a CI failure", "mockup of a login page").

When NOT to use

• Your model supports image input (its model config lists image in input): just read the image directly — no subagent needed.
• The "image" is actually a text, SVG, or code file: read it directly instead.