Agent skill

rozi ships an Agent Skill: a SKILL.md file that teaches coding agents such as Claude Code how to inspect and control rozi panes and sessions with the rozi CLI. This page covers what the skill lets an agent do and how to install, refresh, and remove it.

What the agent can do

With the skill installed, an agent can use rozi when you ask for it, and whenever its task needs a real terminal:

• list panes, read the layout, and capture pane output as text or as an image;
• split panes, run commands in them, send keys, and wait for the output;
• show you a live preview of an app in a pane beside your work;
• test a terminal app by pressing keys and checking what the screen shows;
• record a pane or the whole UI and export the recording;
• start coding agents in other panes, prompt them, wait for them, and read their answers through rozi agents, or ask them a question and answer theirs without waiting;
• control a detached named session with --session, on this machine or over SSH with --remote;
• start a session of its own with rozi sessions new <NAME> --detach --no-resurrect for test runs and captures you did not ask to see, so its panes stay out of your workspaces and it is never offered for restoring.

The skill tells the agent to read live pane IDs instead of guessing them, and to change only the panes and sessions you name or it created. Work you did not ask to see goes in the agent's own session. The agent controls the current UI only from inside one of that UI's panes. For the commands themselves, see Control CLI and Scripting.

For contributors doing visual reviews in this repository, the separate rozi visual skill covers preview panes, screenshots, live animation recordings, and playable exports. It uses rozi's capture and recording commands; it does not replace tui-lipan-visual or tui-lipan-app-builder. This repository-local workflow is not installed by rozi skill install. It reads the actual binary's control contract with rozi skill print, without requiring a separately installed user-facing skill.

Install the skill

Install it for one project, from anywhere inside it:

rozi skill install

This writes .agents/skills/rozi/SKILL.md at the root of the Git checkout you run it in, or in the current directory outside a checkout. skill status and skill uninstall find the project the same way. Use a project install when the instructions should travel with one repository.

Or install it for your user, so agents see it in every project:

rozi skill install --global

This writes ~/.agents/skills/rozi/SKILL.md, or %USERPROFILE%\.agents\skills\rozi\SKILL.md on Windows.

Start or restart the coding-agent session afterwards so it discovers the skill.

Check, refresh, or remove

Check the project or user installation:

rozi skill status
rozi skill status --global

Each report's first line names the installation it describes, such as Rozi skill for project ~/src/app or Rozi skill for user (~); the paths below it are relative to that directory.

rozi skill install is safe to rerun. It refreshes an unchanged copy that rozi installed, and refuses to replace a modified or untracked copy unless you add --force. rozi records each installation's path, content hash, and rozi version in its state directory.

When rozi manages its own installation, rozi update and rozi update --rollback also refresh the global skill and every registered project skill whose content still matches what rozi installed. They leave locally edited copies alone and print a warning. If a skill refresh fails, the binary update still succeeds and prints a warning. Restart coding-agent sessions to load the refreshed instructions.

A project skill installed before rozi tracked installations is not registered, so an update run from elsewhere cannot find it. Run the update from that project and rozi warns about it; then run rozi skill install --force there to replace and register it. Add --global to do the same for the user copy.

Remove only the installation that rozi manages:

rozi skill uninstall
rozi skill uninstall --global

Print without installing

rozi skill print

This writes the embedded SKILL.md to stdout. rozi --skill does the same and must be used without other arguments.

Claude compatibility entry

.agents/skills/rozi is the canonical installation. If claude or claude-code is on PATH, installation also tries to create .claude/skills/rozi, so Claude Code finds the skill:

Platform	Compatibility entry
Linux and macOS	Directory symlink
Windows	Directory junction, or a managed SKILL.md copy when a junction cannot be created

A project symlink is relative where possible. If the compatibility entry cannot be created, the canonical installation stays in place. Uninstalling removes the compatibility entry only when rozi manages it; an unrelated directory already at .claude/skills/rozi is left alone.