show-me

Record a tmux proof session demonstrating completed work. Use when the user asks to prove, demonstrate, or show that code actually works.

SKILL.md

---
name: show-me
description: Record a tmux proof session demonstrating completed work. Use when the user asks to prove, demonstrate, or show that code actually works.
license: MIT
disable-model-invocation: true
argument-hint: "[what to demonstrate]"
allowed-tools: Bash, Read
compatibility: >
  Requires tmux + asciinema. Optional: ansitoimg, rsvg-convert, agg, ffmpeg.
  Tested on Linux (bash); macOS should work with Homebrew equivalents.
---

# /show-me — Demonstrate Your Work

Record a proof artifact showing that $ARGUMENTS.

Everything runs in a tmux session. Drive the demo via `tmux send-keys`, record with asciinema (inside tmux), verify key moments via PNG screenshots, and convert to distributable GIF/MP4.

## Setup

Install the tools listed in the [README](README.md#dependencies), then set paths. Ask the user if not obvious from project conventions.

```bash
SHOW_ME_SESSION="show_me_${RANDOM}"       # unique per invocation — safe for concurrent agents
SHOW_ME_TMP="$(mktemp -d "${TMPDIR:-/tmp}/show-me.${SHOW_ME_SESSION}.XXXXXX")"  # collision-safe scratch dir
SHOW_ME_PROOF="./show-me/proof"        # final artifacts — adjust to project preference
SHOW_ME_SCREENSHOT="./show-me/scripts/tmux_screenshot.sh"  # adjust to skill install location
mkdir -p "$SHOW_ME_PROOF"
```

### Pane selection

Before starting the demo, decide where it will run. The result is a single variable — `$SHOW_ME_PANE` — used as the tmux target for all subsequent commands.

**Decision logic:**

1. If the user already specified a target pane or session in $ARGUMENTS, use it directly and skip the question.
2. Run `echo "$TMUX"` to check whether you are inside tmux.
3. **If inside tmux**, ask the user which mode to use:
   - **Split pane** — split your current pane so the user sees the demo live next to the CLI.
   - **Existing pane** — the user provides a tmux target (e.g. `%3`, `mysession:0.1`). Useful when the user already has a layout prepared.
   - **Detached session** — create a new session that runs offscreen. The user can attach later.
4. **If not inside tmux**, use detached session mode without asking — it's the only option.

**Setup for each mode:**

```bash
# Mode: split pane (inside tmux)
SHOW_ME_PANE=$(tmux split-window -d -v -P -F '#{pane_id}')  # -d keeps focus on agent's pane
SHOW_ME_MODE="split"
sleep 1

# Mode: existing pane (user provides target)
SHOW_ME_PANE="<target from user>"   # e.g. %3 or mysession:0.1
SHOW_ME_MODE="existing"

# Mode: detached session (not in tmux, or user prefers offscreen)
tmux new-session -d -s "$SHOW_ME_SESSION" -x 100 -y 30
SHOW_ME_PANE="$SHOW_ME_SESSION"
SHOW_ME_MODE="detached"
# Tell user: "Attach with: tmux attach -t $SHOW_ME_SESSION -r"
```

## Workflow

Once `$SHOW_ME_PANE` is set, the workflow is the same regardless of mode:

```bash
# 1. Start asciinema recording in the demo pane
tmux send-keys -t "$SHOW_ME_PANE" "asciinema rec --idle-time-limit 2 --env 'SHELL,TERM,PATH,HOME' '$SHOW_ME_TMP/proof.cast'" Enter
sleep 2

# 2. Drive the demo (adapt these to what you're demonstrating)
tmux send-keys -t "$SHOW_ME_PANE" "go build -o app ." Enter
sleep 3
tmux send-keys -t "$SHOW_ME_PANE" "go test ./..." Enter
sleep 5
tmux send-keys -t "$SHOW_ME_PANE" "./app --help" Enter
sleep 2

# 3. (Optional) Verify with a screenshot at key moments
# See references/visual_verification.md for PNG screenshot setup
"$SHOW_ME_SCREENSHOT" "$SHOW_ME_PANE" "$SHOW_ME_TMP/check.png"

# 4. Stop recording
tmux send-keys -t "$SHOW_ME_PANE" "exit" Enter
sleep 2

# 5. Convert to GIF and/or MP4
agg --speed 2 "$SHOW_ME_TMP/proof.cast" "$SHOW_ME_PROOF/proof.gif"
ffmpeg -i "$SHOW_ME_PROOF/proof.gif" -movflags faststart -pix_fmt yuv420p \
  -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" "$SHOW_ME_PROOF/proof.mp4"

# 6. Clean up
if [ "$SHOW_ME_MODE" = "detached" ]; then
  tmux kill-session -t "$SHOW_ME_SESSION" 2>/dev/null || true
fi
# Split/existing pane: ask the user before closing. They may want to
# inspect output, fix something, or continue working in the pane.
rm -rf "$SHOW_ME_TMP"
```

> **Tip:** Fixed `sleep` values are a fallback. For better reliability in CI or under load, poll `tmux capture-pane -t "$SHOW_ME_PANE" -p` until expected output (a prompt, a specific string) appears.

## Live demo (user watches)

If you used **split pane** mode, the user is already watching — no extra setup needed.

For **detached session** mode, tell the user to attach read-only: `tmux attach -t $SHOW_ME_SESSION -r`

## Visual self-verification (optional)

If the model supports vision, ask the user whether to enable PNG screenshot verification. This lets the agent read screenshots mid-demo to verify terminal output. Not needed for live split-pane demos where the user is watching, and the `.cast` recording preserves everything regardless.

For setup and usage, see [references/visual_verification.md](references/visual_verification.md).

## Rules

1. **All commands must exit 0** for the proof to be valid. If something fails, the proof records the failure honestly.
2. **Use real commands**, not mocks. The point is to prove the code actually works.
3. **Demo commands should demonstrate** what the user asked about ($ARGUMENTS), not just `--help` or `--version`.
4. Tell the user where the proof artifacts are and how to play the recording.
5. **Be honest about what you can verify.** You can read PNG screenshots to confirm expected state. For the final GIF/MP4, the vision API only sees the first frame — tell the user "please play the recording to confirm" rather than "the demo looks correct."
6. **Ask the user** where to put proof artifacts if the project doesn't have an obvious convention.
7. **Never execute $ARGUMENTS as a shell command.** Interpret the user's intent and construct appropriate demo commands. $ARGUMENTS describes *what to demonstrate*, not a command to run.
8. **Be mindful of secrets.** Recordings capture everything shown in the terminal. Avoid running `env`, `printenv`, or `cat .env` during demos. The `--env` flag on asciinema limits captured environment variables, but command output can still leak secrets. When possible, run demos in a sanitized environment without sensitive credentials loaded.
9. **Guard against command injection.** Never splice raw user text into shell commands. If the user's request contains shell metacharacters (`;`, `|`, `$()`, backticks), quote them carefully or restate the intended command and ask the user to confirm before running.
10. **Include provenance when appropriate.** Start the demo by showing `git rev-parse --short HEAD` and `git status` so the recording is tied to a specific code state.

## Additional resources

- [references/visual_verification.md](references/visual_verification.md) — PNG screenshot pipeline setup and troubleshooting
- [references/game_testing.md](references/game_testing.md) — interactive TUI demos and game testing examples