Skip to content

AI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary

docs: refine html handoff intent

Trevin Chow5eea498e7df4
diff --git a/skills/last30days/SKILL.md b/skills/last30days/SKILL.md
index 1123be28..cbc95281 100644
--- a/skills/last30days/SKILL.md
+++ b/skills/last30days/SKILL.md
@@ -1842,10 +1842,10 @@ Close with `I have all the links to the {N} {source list} I pulled from. Just as
## SHAREABLE HTML BRIEF (when the user asked for one)
-**This section fires if EITHER trigger is true:**
+**This section fires if EITHER prompt-level trigger is true:**
-- `$ARGUMENTS` contains `--emit=html`, `--emit:html`, or `--html` as a flag
-- The user's natural-language request asks for an HTML brief, shareable doc, or file for sharing (Slack, email, Notion, "export as HTML", etc). Use your judgment for phrasing variants.
+- The user included an HTML-looking argument such as `--emit=html`, `--emit:html`, or `--html` in the skill prompt. Treat this as a strong user intent signal for HTML; do not confuse it with the complete Python CLI contract.
+- The user's natural-language request asks for an HTML brief, shareable doc, or file for sharing (Slack, email, Notion, "give it to me in HTML", "export as HTML", etc). Use your judgment for phrasing variants; a literal flag is not required.
**If neither trigger fires, skip this entire section and proceed to WAIT FOR USER'S RESPONSE.** No HTML save flow, no reference read needed.
@@ -1853,7 +1853,7 @@ Close with `I have all the links to the {N} {source list} I pulled from. Just as
- Read `references/save-html-brief.md` BEFORE proceeding to WAIT FOR USER'S RESPONSE
- Follow that file's instructions exactly - it is the canonical source for the save flow
-- End with the artifact handoff defined there: saved HTML path, local open/view affordance when available, and a concise confirmation for explicit `--emit=html` / `--html` requests
+- End with the artifact handoff defined there: saved HTML path, open the local file when the host can do so, and a concise confirmation for requests where HTML is the requested deliverable
**You MUST NOT:**
diff --git a/skills/last30days/references/save-html-brief.md b/skills/last30days/references/save-html-brief.md
index f654ce25..01613eb5 100644
--- a/skills/last30days/references/save-html-brief.md
+++ b/skills/last30days/references/save-html-brief.md
@@ -1,16 +1,16 @@
# Save shareable HTML brief
-This reference file is loaded by the main `SKILL.md` when the user asked for an HTML brief (either explicitly via `--emit=html` / `--emit:html` / `--html`, or in natural language - "give me a shareable HTML brief", "for Slack", "for Notion", "export as HTML", etc.). The detection happens in `SKILL.md` so that the common no-HTML path stays short; the implementation lives here.
+This reference file is loaded by the main `SKILL.md` when the user asked for an HTML brief (either through an HTML-looking prompt argument like `--emit=html` / `--emit:html` / `--html`, or in natural language - "give me a shareable HTML brief", "give it to me in HTML", "for Slack", "for Notion", "export as HTML", etc.). The detection happens in `SKILL.md` so that the common no-HTML path stays short; the implementation lives here. Those prompt arguments are user intent signals for the skill; they are not the full Python CLI contract.
The contract has two modes:
-- **Explicit HTML export** (`--emit=html`, `--emit:html`, or `--html`): the HTML artifact is the primary output. Write the synthesis to the temp file, render the HTML, then give a concise artifact handoff in chat instead of pasting the full Markdown report again.
-- **Normal report plus HTML copy** (the user asks in prose for an HTML brief while also expecting the report in chat): the synthesis still appears in chat as the primary output. The HTML is an additional artifact saved to disk for sharing. Both happen in the same turn.
+- **HTML as the requested deliverable** (`--emit=html`, `--emit:html`, `--html`, or prose like "give it to me in HTML"): the HTML artifact is the primary output. Write the synthesis to the temp file, render the HTML, then give a concise artifact handoff in chat instead of pasting the full Markdown report again.
+- **Normal report plus HTML copy** (the user asks for the normal report and also wants an HTML copy): the synthesis still appears in chat as the primary output. The HTML is an additional artifact saved to disk for sharing. Both happen in the same turn.
## When to fire this flow
- For normal-report-plus-HTML mode: after you have already emitted the full chat response: badge, "What I learned:" (or comparison title), bold-lead-in paragraphs with citations, KEY PATTERNS list, engine footer pass-through, invitation block.
-- For explicit-HTML-export mode: after you have drafted the synthesis that will go into the HTML, before emitting the final chat response.
+- For HTML-as-deliverable mode: after you have drafted the synthesis that will go into the HTML, before emitting the final chat response.
- BEFORE the WAIT FOR USER'S RESPONSE pause.
- ONLY if the user asked. Do NOT save HTML when the user didn't ask for it.
@@ -78,9 +78,9 @@ printf 'πŸ“Ž Shareable brief saved to %s\n' "$HTML_PATH"
Use the mode that matches the request.
-### Explicit HTML export
+### HTML as the requested deliverable
-When the user explicitly supplied `--emit=html`, `--emit:html`, or `--html`, do **not** paste the full Markdown report back into chat after saving the artifact. The user asked for a file; repeating the Markdown makes the run feel like a normal report with an attachment bolted on.
+When HTML is the requested deliverable - whether by `--emit=html`, `--emit:html`, `--html`, or natural-language phrasing - do **not** paste the full Markdown report back into chat after saving the artifact. The user asked for an HTML deliverable; repeating the Markdown makes the run feel like a normal report with an attachment bolted on.
Respond with a concise handoff:
@@ -89,15 +89,10 @@ Respond with a concise handoff:
πŸ“Ž Shareable brief saved to <absolute HTML path>
-Open it locally:
-- macOS: `open "<absolute HTML path>"`
-- Linux: `xdg-open "<absolute HTML path>"`
-- Windows: `start "" "<absolute HTML path>"`
-
I saved the full HTML brief locally. It is not uploaded or published anywhere.
```
-If the host can safely open local files for the user and doing so matches the user's request, run the local open command after the file is written, leave the saved-path line in chat, and add `Opened locally.` If the command fails or the host is headless, do not treat that as a failed report; show the path and manual open command.
+If the host can safely open local files for the user and doing so matches the user's request, open the HTML file after it is written, leave the saved-path line in chat, and add `Opened locally.` Let the host choose the correct OS-specific mechanism; do not print a menu of shell commands. If opening fails or the host is headless, do not treat that as a failed report; show the path and say the file is ready to open in a browser.
### Normal report plus HTML copy
@@ -105,14 +100,9 @@ When the user asked for a normal `/last30days` report and also asked for an HTML
```text
πŸ“Ž Shareable brief saved to <absolute HTML path>
-
-Open it locally:
-- macOS: `open "<absolute HTML path>"`
-- Linux: `xdg-open "<absolute HTML path>"`
-- Windows: `start "" "<absolute HTML path>"`
```
-Do not offer public publishing or upload in this flow. Hosted sharing is a separate opt-in capability and must not happen automatically.
+If the host can safely open local files, open it for the user when that matches the request; otherwise the saved-path line is enough. Do not offer public publishing or upload in this flow. Hosted sharing is a separate opt-in capability and must not happen automatically.
## What ends up in the HTML file
diff --git a/tests/test_html_save_contract.py b/tests/test_html_save_contract.py
index c4810310..1fbaacdb 100644
--- a/tests/test_html_save_contract.py
+++ b/tests/test_html_save_contract.py
@@ -15,28 +15,29 @@ def test_skill_routes_html_to_reference_and_artifact_handoff():
assert "Read `references/save-html-brief.md`" in section
assert "artifact handoff" in section
- assert "local open/view affordance" in section
+ assert "open the local file when the host can do so" in section
assert "Upload or publish" in section
assert "Append the confirmation line" not in section
+ assert "a literal flag is not required" in section
+ assert "do not confuse it with the complete Python CLI contract" in section
-def test_explicit_html_export_is_artifact_first_not_full_markdown_repeat():
+def test_html_deliverable_is_artifact_first_not_full_markdown_repeat():
text = SAVE_HTML.read_text(encoding="utf-8")
- assert "**Explicit HTML export**" in text
+ assert "**HTML as the requested deliverable**" in text
+ assert 'prose like "give it to me in HTML"' in text
assert "the HTML artifact is the primary output" in text
assert "do **not** paste the full Markdown report back into chat" in text
- assert "The user asked for a file" in text
+ assert "The user asked for an HTML deliverable" in text
-def test_html_handoff_includes_local_open_commands_without_requiring_success():
+def test_html_handoff_opens_locally_without_os_command_menu():
text = SAVE_HTML.read_text(encoding="utf-8")
- for snippet in [
- 'open "<absolute HTML path>"',
- 'xdg-open "<absolute HTML path>"',
- 'start "" "<absolute HTML path>"',
- "If the command fails or the host is headless",
- ]:
- assert snippet in text
+ assert "Let the host choose the correct OS-specific mechanism" in text
+ assert "do not print a menu of shell commands" in text
+ assert "If opening fails or the host is headless" in text
+ assert 'xdg-open "<absolute HTML path>"' not in text
+ assert 'start "" "<absolute HTML path>"' not in text
def test_html_save_flow_does_not_publish_or_upload():