From 0facc63019e6f7b88d04883466603af80779f384 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 15 Jan 2026 10:14:59 +0000
Subject: [PATCH] fix(skills): improve summarize selection

---
 skills/summarize/SKILL.md                     | 20 ++++++++++++++++++-
 ...skills.summarize-skill-description.test.ts | 19 ++++++++++++++++++
 2 files changed, 38 insertions(+), 1 deletion(-)
 create mode 100644 src/agents/skills.summarize-skill-description.test.ts

diff --git a/skills/summarize/SKILL.md b/skills/summarize/SKILL.md
index df9e23969..0ba28d878 100644
--- a/skills/summarize/SKILL.md
+++ b/skills/summarize/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: summarize
-description: Summarize URLs or files with the summarize CLI (web, PDFs, images, audio, YouTube).
+description: Summarize or extract text/transcripts from URLs, podcasts, and local files (great fallback for “transcribe this YouTube/video”).
 homepage: https://summarize.sh
 metadata: {"clawdbot":{"emoji":"🧾","requires":{"bins":["summarize"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/summarize","bins":["summarize"],"label":"Install summarize (brew)"}]}}
 ---
@@ -9,6 +9,14 @@ metadata: {"clawdbot":{"emoji":"🧾","requires":{"bins":["summarize"]},"install
 
 Fast CLI to summarize URLs, local files, and YouTube links.
 
+## When to use (trigger phrases)
+
+Use this skill immediately when the user asks any of:
+- “use summarize.sh”
+- “what’s this link/video about?”
+- “summarize this URL/article”
+- “transcribe this YouTube/video” (best-effort transcript extraction; no `yt-dlp` needed)
+
 ## Quick start
 
 ```bash
@@ -17,6 +25,16 @@ summarize "/path/to/file.pdf" --model google/gemini-3-flash-preview
 summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto
 ```
 
+## YouTube: summary vs transcript
+
+Best-effort transcript (URLs only):
+
+```bash
+summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto --extract-only
+```
+
+If the user asked for a transcript but it’s huge, return a tight summary first, then ask which section/time range to expand.
+
 ## Model + keys
 
 Set the API key for your chosen provider:
diff --git a/src/agents/skills.summarize-skill-description.test.ts b/src/agents/skills.summarize-skill-description.test.ts
new file mode 100644
index 000000000..ca0d67c6d
--- /dev/null
+++ b/src/agents/skills.summarize-skill-description.test.ts
@@ -0,0 +1,19 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { parseFrontmatter } from "./skills/frontmatter.js";
+
+describe("skills/summarize frontmatter", () => {
+  it("mentions podcasts, local files, and transcription use cases", () => {
+    const skillPath = path.join(process.cwd(), "skills", "summarize", "SKILL.md");
+    const raw = fs.readFileSync(skillPath, "utf-8");
+    const frontmatter = parseFrontmatter(raw);
+    const description = frontmatter.description ?? "";
+    expect(description.toLowerCase()).toContain("transcrib");
+    expect(description.toLowerCase()).toContain("podcast");
+    expect(description.toLowerCase()).toContain("local files");
+    expect(description).not.toContain("summarize.sh");
+  });
+});