# Agent Usage

Open Record/Replay is designed to be called through local commands.

The agent does not need to share Codex's Computer Use protocol. Computer Use is the execution layer supplied by the host agent. Open Record/Replay only records the user's demonstrated desktop workflow and produces evidence for that host agent's native skill creator:

```text
session.json
events.jsonl
skill-inputs/<session-id>/
```

Use [../skills/open-record-replay/SKILL.md](../skills/open-record-replay/SKILL.md) as the host-agent instruction template. It is the equivalent of the official Record & Replay skill instructions, but mapped to this project's CLI.

## Integration Contract

An agent integration needs:

- Local access to the `orr` CLI.
- macOS Accessibility/Input Monitoring permission for the native recorder.
- A way to ask the user to perform a demonstration.
- A native skill creation mechanism for the host agent.
- Computer Use-like execution if the generated skill should operate desktop apps.

Use CLI mode when the host agent can run shell commands.

```bash
orr permissions check
orr record start --name my-workflow --out runs
```

If `permissions.recorderReady` is false, the agent should run `orr permissions request`, tell the user exactly which macOS permissions are missing, and wait for the user to enable them before starting the recording.

The agent should then stop its turn and ask the user to perform the workflow. When the user returns:

```bash
orr record stop latest --out runs
orr session validate-recording latest --out runs
orr skill prepare latest --runs runs --out skill-inputs
```

The generated package is:

```text
skill-inputs/<session-id>/
├── README.md
├── events.jsonl
└── session.json
```

The host agent should read `README.md`, inspect `events.jsonl` as the primary evidence, then invoke its own native skill creator to create, install, and validate the final skill artifact.

The core path is Record -> Events -> Skill Evidence Package -> Host-Native Skill Creator.

## Host Skill Creation

The evidence package does not contain a generated workflow summary. This is intentional.

Open Record/Replay must not be treated as the final skill authoring layer. It prepares evidence only. The host agent is responsible for calling its own native skill creator because each agent owns different skill schema, install paths, validation rules, discovery metadata, and runtime assumptions.

Examples:

- Codex integration should hand the package to Codex `skill-creator`.
- Claude Code integration should hand the package to Claude Code's native skill authoring/install flow.
- Generic agents without native skill support may consume the package as a runbook input, but should not claim that a host-native skill was created.

The host agent should:

- Treat `events.jsonl` as source of truth.
- Create the final skill using its own native skill creation mechanism.
- Break the demonstrated workflow into Computer Use nodes.
- Parameterize reusable inputs such as file path, recipient, URL, search query, prompt, or message text.
- Add verification and fallback steps for each side-effect action.
- Ask the user when a key action is ambiguous.

## Host-Native Skill Output

The final skill artifact is host-owned. Do not force every agent into the same file layout or install path.

When the host's native creator writes Markdown-based skills, prefer content with this shape:

```markdown
---
name: example-skill
description: What the skill does and when to use it.
---

# Example Skill

## Inputs
## Computer Use Workflow
## Verification
## Fallbacks
## Safety Rules
```

The same evidence package can guide multiple agents, but each final installed skill should be generated by that agent's native creator.

## Safety

- Do not record without explicit user intent.
- Do not include secrets or private personal data in generated skills.
- Do not infer unsupported actions from generic AX targets.
- Confirm destinations before sending messages, uploading files, posting comments, or publishing content.
- Keep raw `events.jsonl` local unless the user explicitly exports it.