85 lines
5.3 KiB
Markdown
85 lines
5.3 KiB
Markdown
---
|
|
name: artifact-presenter
|
|
description: "Present local artifacts for review: use Browser Harness for interactive web artifacts, Orca for editor-friendly text in Orca-managed sessions, and mcat for other non-web files."
|
|
---
|
|
|
|
# Artifact presenter
|
|
|
|
Present reviewable files and substantial generated content through the appropriate viewer instead of duplicating the complete artifact in chat.
|
|
|
|
## Choose the artifact
|
|
|
|
Use this workflow in either case:
|
|
|
|
- The user needs to review one local file, regardless of its length or format.
|
|
- The expected deliverable is a structured report, plan, ADR, review, or summary with several substantive sections or roughly 1,000 words.
|
|
|
|
Treat an explicit destination and format as authoritative. For generated content without a requested destination:
|
|
|
|
- Use `/tmp/pi-present/<descriptive-slug>.<extension>`.
|
|
- Default structured prose to Markdown when no other format is implied.
|
|
- Create `/tmp/pi-present/` when needed.
|
|
- Add a timestamp only when replacing an earlier artifact would lose useful information.
|
|
|
|
Keep ordinary explanations, code diffs, logs, multi-file comparisons, and user-requested inline responses in chat. Present a file only when it is a user-facing review artifact, not merely because the agent read it during investigation.
|
|
|
|
Choose the presentation path:
|
|
|
|
- **Interactive web artifacts, especially `.html`:** use the Browser Harness/Browser Use-backed workflow.
|
|
- **Non-web artifacts:** run this skill's presenter helper. It opens editor-friendly UTF-8 text directly in Orca when the harness is running in an Orca-managed terminal; otherwise it uses mcat in the reusable Herdr pane. Binary and media files stay on the mcat path.
|
|
|
|
Completion criterion: select exactly one existing or generated artifact path before presentation.
|
|
|
|
## Prepare generated content
|
|
|
|
Write the complete deliverable to the selected path. Keep it self-contained: the reader must not need omitted chat text to understand it.
|
|
|
|
Preserve repository documentation conventions. Creating a presentation artifact under `/tmp` does not authorize editing repository files when the request is otherwise read-only.
|
|
|
|
When presenting an existing non-web file, pass the original file directly to mcat. Do not create a converted copy merely for display.
|
|
|
|
Completion criterion: the selected file exists and contains the complete review artifact.
|
|
|
|
## Present interactive web artifacts
|
|
|
|
Load and follow the [`browser-harness`](../browser-harness/SKILL.md) skill. Open the local artifact URL in a real browser through the Browser Harness/Browser Use-backed workflow, then verify the browser target reports the artifact URL and page title. When normal Chrome attachment is unavailable, use browser-harness's documented local HTML fallback.
|
|
|
|
Completion criterion: the active browser target reports the local artifact URL and page title.
|
|
|
|
## Present non-web artifacts
|
|
|
|
Run the helper using its absolute path resolved from this skill directory:
|
|
|
|
```bash
|
|
python3 <skill-directory>/scripts/present.py <artifact-path>
|
|
```
|
|
|
|
The helper detects an Orca-managed harness from Orca's terminal environment markers (`TERM_PROGRAM=Orca` or scoped `ORCA_*` workspace, worktree, pane, or terminal IDs). For editor-friendly UTF-8 text, it resolves the session's version-appropriate CLI and runs `orca file open <artifact-path> --json`. Orca only opens paths inside its selected worktree, so a rejected path falls through to the normal non-web fallback.
|
|
|
|
The fallback reuses the pane labeled `artifact presenter` in the current Herdr workspace. It serializes pane discovery, creation, and replacement per workspace, with an additional per-pane lock during viewer handoff. When that pane is already displaying an artifact, it closes the active `mcat` viewer and waits for the pane shell before launching the replacement through a shell-neutral helper command with encoded path arguments. It confirms the helper started the viewer rather than trusting terminal input delivery alone. It leaves unrelated foreground programs untouched and creates a new viewer pane instead. When no reusable pane exists, it creates a right split without taking focus. It launches `mcat <artifact-path>` so mcat can infer and display documents, source, archives, PDFs, images, and videos. It falls back to artifact-only delivery when neither Orca nor the Herdr/mcat path can present the file.
|
|
|
|
Completion criterion: capture whether Orca opened the file, the helper opened or reused an mcat pane, or presentation fell back to the artifact path only.
|
|
|
|
## Convert only when requested
|
|
|
|
Use mcat's conversion pipeline when the user requests a derivative artifact:
|
|
|
|
```bash
|
|
mcat <input> --output md > <output.md>
|
|
mcat <input> --output html > <output.html>
|
|
mcat <input> --output image > <output.png>
|
|
```
|
|
|
|
Use an explicit output path and preserve the source file. Present the resulting single file through the matching presentation path above when the user needs to review it.
|
|
|
|
## Respond concisely
|
|
|
|
Return:
|
|
|
|
- a one- to three-sentence result summary;
|
|
- the artifact path;
|
|
- for interactive web artifacts, that Browser Harness presented the artifact and verified its URL/title;
|
|
- for other artifacts, whether Orca opened the file, the reusable mcat pane was opened or reused, or why presentation fell back to the file only.
|
|
|
|
Do not repeat the complete artifact in chat. Honor a later request to paste any section inline.
|