Ship a programa agent skill: packaged instructions so agents can drive the app

[arzafran]

Agents running inside programa already have everything they need to drive the app (socket API, programa CLI, PROGRAMA_SURFACE_ID / PROGRAMA_SOCKET_PATH exported by shell integration), but nothing teaches them it exists. Packaging the instructions is the cheapest, highest-leverage item on the agent-first list.

What it is

A SKILL.md (repo root, plus a docs page) that teaches an agent to:

• inspect its surroundings: workspaces, tabs, panes, sibling agents
• split panes and run commands without stealing the user's focus
• read output from sibling panes (build logs, test runners, another agent)
• spawn a helper agent in a sibling pane and coordinate with it
• wait on servers, tests, or another agent (gets much better once surface.wait and agent.prompt: server-owned waits on the socket #166 lands, works with polling today)

Guard

First instruction in the skill: if PROGRAMA_SURFACE_ID / PROGRAMA_SOCKET_PATH are not set, stop and say you are not running inside programa. No env, no socket calls.

Tasks

1. Write SKILL.md covering the commands above with copy-paste examples (verify: fresh Claude Code session inside programa, told to "open a split and tail the dev server log", does it via the CLI without focus theft)
2. Docs page + README pointer
3. Make it installable the way agent skills normally are (skills CLI / plugin folder), and have our Claude/Codex/OpenCode install flows drop it in place