71 lines
3.8 KiB
Markdown
71 lines
3.8 KiB
Markdown
---
|
|
name: artifact-presenter
|
|
description: Present any single local file the user needs to review, including documents, source, archives, PDFs, images, and videos, through mcat in a reusable Herdr pane. Also use for structured long-form reports, plans, ADRs, reviews, and summaries unless the user requests inline chat.
|
|
---
|
|
|
|
# Artifact presenter
|
|
|
|
Present reviewable files and substantial generated content in a reusable terminal document pane 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.
|
|
|
|
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 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 with mcat
|
|
|
|
Run the helper using its absolute path resolved from this skill directory:
|
|
|
|
```bash
|
|
python3 <skill-directory>/scripts/present.py <artifact-path>
|
|
```
|
|
|
|
The helper 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 Herdr or mcat is unavailable.
|
|
|
|
Completion criterion: capture whether the helper opened, reused, or skipped the viewer pane.
|
|
|
|
## 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 helper when the user needs to review it.
|
|
|
|
## Respond concisely
|
|
|
|
Return:
|
|
|
|
- a one- to three-sentence result summary;
|
|
- the artifact path;
|
|
- whether 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.
|