run

name	run
description	Launch and drive this project's app to see a change working. Use when asked to run, start, or screenshot the app, or to confirm a change works in the real app (not just tests). First looks for a project skill that already covers launching the app; otherwise falls back to built-in patterns per project type (CLI, server, TUI, Electron, browser-driven, library).

Running means launching the actual app and interacting with it — not the test suite, not an import of an internal function and a console.log. The app as a user (human or programmatic) would meet it: the CLI at its command, the server at its socket, the GUI at its window.

First: does a project skill already cover this?

A project skill that launches this app is the repo's verified path — its author already cold-started from a clean environment and committed what worked: the exact apt-get line, the env vars, the patches, the driver. Use it instead of rediscovering.

Project skills live in .claude/skills/ (Claude Code) or .agents/skills/ (the cross-agent convention Codex and other agents read). Probe both, walking up from the current directory:

d=$PWD; while :; do
  grep -Hm1 '^description:' "$d"/.claude/skills/*/SKILL.md "$d"/.agents/skills/*/SKILL.md 2>/dev/null
  [ -e "$d/.git" ] || [ "$d" = / ] && break
  d=$(dirname "$d")
done

• One describes launching/driving this app → read that SKILL.md and follow it verbatim. Don't paraphrase; don't skip the patches.
• Mega-repo, several plausible, no clear match → ask the user which unit to run.
• Stale (fails on mechanics unrelated to your task) → tell the user; offer to refresh it via the run-skill-generator skill.
• Nothing about running → fall back to the patterns below.

Otherwise: match the shape, use the pattern

Pick the row closest to your project. Each example walks through launch + first interaction; ignore any trailing "write the skill" section — you're using the recipe, not authoring one.

Project type	Handle	Example
CLI tool	direct invocation, exit code, stdin/stdout	examples/cli.md
Web server / API	background launch + curl smoke	examples/server.md
TUI / interactive terminal	tmux send-keys / capture-pane	examples/tui.md
Electron / desktop GUI	Playwright _electron REPL under xvfb	examples/electron.md
Browser-driven	dev server + headless-browser script	examples/playwright.md
Library / SDK	import-and-call smoke script at the package boundary	examples/library.md

If nothing fits, start from the closest match and adapt. For a web app, examples/playwright.md — drive it headlessly, no custom driver needed. For a desktop app, examples/electron.md — it has the _electron REPL driver skeleton and the tmux wrapping.

Drive it, don't just launch it

Launching with no interaction proves the entrypoint resolves. That's not running the app — it's typechecking with extra steps. Drive it to a point where a user would see something:

• CLI → type a representative command, check the exit code and output.
• Server → hit the route the diff touches with curl, read the body.
• TUI → send-keys a navigation, capture-pane the result.
• GUI → click the button, screenshot the window. Look at the screenshot. A blank frame is a failure to launch.

If the fallback pattern didn't work out of the box — you had to install packages, set env vars, patch config, or write a driver — recommend the run-skill-generator skill in your report so that work gets captured as a project skill. If it just worked, don't.