feat(skills): add artifact presenter

2026-08-26 19:13:41 -04:00
parent bee84be4c3
commit 419414c4c3
5 changed files with 496 additions and 1 deletions
@@ -0,0 +1,70 @@
+---
+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. When none exists, it creates a right split without taking focus. It invokes `mcat <artifact-path>` directly 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.