image-vision skill broken on macOS (amplifier-bundle-skills): GNU `timeout` not portable, install path mismatch

[Joi]

Filing here because microsoft/amplifier-bundle-skills has issues disabled. Please retarget if there's a better venue.

Summary

The image-vision skill in amplifier-bundle-skills is structurally broken on macOS. Two compounding bugs make every screenshot/vision attempt fail:

1. vision-analyze-robust.sh line 68 calls GNU timeout, which is not installed on macOS by default (BSD does not include it).
2. The skill's invocation path ~/.amplifier/skills/image-vision/vision-analyze-robust.sh doesn't exist after install — the file lives only in the cache at ~/.amplifier/cache/amplifier-bundle-skills-*/skills/image-vision/. There's no symlink/copy step into ~/.amplifier/skills/.

Evidence

Six distinct sessions across three days (April 28 – April 30) all failed identically:

sh: line 68: timeout: command not found

Sessions: 0000000000000000-5c9223a9d4344e09, 0000000000000000-e5726edfd6f14d73, 0000000000000000-3c32a4fec5a6475d (×4), 0000000000000000-94544ef4e4e148c4 (×3), 0000000000000000-6938b0b351f949ab (×2), 0000000000000000-f34d9190ed6b416b.

Bug 1: timeout not portable

skills/image-vision/vision-analyze-robust.sh line 68 invokes timeout N $cmd directly. On macOS, the GNU timeout binary is not present (it's part of coreutils, optionally available as gtimeout via brew install coreutils).

Fix options:

• Detect gtimeout and prefer it; fall back to timeout.
• Use a portable Perl wrapper: perl -e 'alarm shift; exec @ARGV' "$TIMEOUT_SECS" "$VENV_DIR/bin/python" ....
• Use a Python subprocess wrapper with subprocess.run(..., timeout=N).

The Perl trick is cleanest — Perl is on every macOS by default.

Bug 2: install path mismatch

The skill's documentation/SKILL.md tells the agent to invoke vision-analyze-robust.sh (relative path), but it only exists at:

~/.amplifier/cache/amplifier-bundle-skills-<hash>/skills/image-vision/vision-analyze-robust.sh

There is no copy or symlink at ~/.amplifier/skills/image-vision/ (the user-installed location), so unless the agent's cwd happens to be inside the cache directory (which it never is during normal use), the script can't be found.

Fix options:

• Add a stable installer step that symlinks ~/.amplifier/cache/.../skills/* into ~/.amplifier/skills/ at amplifier update time, OR
• Document in SKILL.md that scripts must be invoked using a resolved-at-load-time variable, OR
• Inline the invocation logic so SKILL.md doesn't need to call out to a sibling script.

Cross-reference

Tracked downstream as joi-n4f in our amplifier-bundle-joi beads project. Six-session evidence trail above. Happy to test patches against macOS 26.4.1 arm64.