git:20260416.83f6907 to git:20260417.89d056b

199 added, 77 removed. Audit A to A.

---

name: lai-summarize

- description: Summarize a transcript, podcast, or long caption file into structured markdown (TL;DR, chapters with timestamps, quotes, entities). **Primary path uses this session's LLM directly — no API key, no model config.** Trigger on "summarize", "生成摘要", "总结", "TL;DR", "episode summary", "what was discussed", or when the user has a long caption and wants key points. CLI `lai summarize caption` is the secondary path for oversized transcripts / headless runs.

+ model: sonnet

+ description: Use when generating a summary from captions, transcripts, or audio content. Agent-driven summarization using the agent's own LLM ability for highest quality. Falls back to CLI when needed. Use this skill whenever the user has a transcript, podcast, interview, or long caption file and wants a condensed overview, chapter summary, or key takeaways. Also triggers on "summarize", "生成摘要", "总结内容", "write summary", "episode summary", "总结这个播客", "what was discussed", "give me the highlights", "TL;DR", even if they just say "this transcript is really long, what are the main points?".

---

# Content Summarizer

- > **Preferred model: Claude Sonnet** (cost-efficient for this agent-driven workload). This skill runs on whatever model is active in the parent session — any Claude model works; no hard switch.

+ **Agent-driven summarization.** The agent reads transcripts/captions and

+ writes structured summaries directly -- no external LLM API call by default.

+ Falls back to `lai summarize caption` (CLI with configurable LLM backend)

+ when the agent cannot process the content directly (e.g., very large files).

- This skill summarizes using **the agent's own LLM capability** — the model you are running right now. It does not call out to any external LLM service by default. Helper scripts turn the source into an agent-ready prompt and validate the finished summary, so the agent only has to write prose.

+ ## When to Use

- **Primary path** (agent-driven, default): `prepare.py` → agent writes summary.md → `validate.py`.

- **Secondary path**: `lai summarize caption` (CLI with its own LLM backend) — only when the transcript is too large for the agent's context, or there is no agent in the loop.

+ - Summarize podcast episodes, interviews, lectures, meetings

+ - Generate chapter-based summaries with timestamps

+ - Create TL;DR from long transcripts

+ - Produce SEO-friendly titles and descriptions

+ - Extract key entities (people, concepts, organizations)

- ## Inputs

+ ## When NOT to Use

- Any caption format supported by `lattifai-captions` (SRT, VTT, ASS, JSON, Gemini markdown, plain text, …).

+ - Need full transcription -- use `/lai-transcribe`

+ - Need translation -- use `/lai-translate`

+ - Need speaker identification -- use `/lai-diarize` (summarize after)

+ - Input is not audio/caption content (articles, web pages)

- Optional `meta.md` beside the source enriches the summary. **If `meta.md` defines `chapters:`, those titles and timestamps are hard constraints** — no merge, split, rename, or reorder.

+ ## Parameters

- `meta.md` **must** wrap its YAML in `---` frontmatter delimiters; otherwise `validate.py` can't parse it and hard constraints are silently skipped (with a warning on stderr). Minimal template:

+ | Parameter | Values | Default |

+ |-----------|--------|---------|

+ | `<source>` | Path to caption/transcript file | required |

+ | `--output <path>` | Output summary file path | `<source>.summary.md` |

+ | `--meta <path>` | Path to meta.md for episode metadata | auto-detect |

+ | `--lang <code>` | Summary language | source language |

+ Length semantics:

+ | Length | Approximate Output |

+ |--------|--------------------|

+ | `short` | 200-400 words, 1 paragraph TL;DR + entity list |

+ | `medium` | 500-1000 words, chapters + quotes + entities |

+ | `long` | 1000-2000 words, detailed chapter summaries + full entity list |

+ ## Output Schema (Markdown)

```markdown

---

title: "Episode Title"

+ seo_title: "SEO-Optimized Title (<=60 chars)"

+ seo_description: "One-sentence description (<=160 chars)"

+ tags: ["tag1", "tag2", "tag3"]

chapters:

- - { title: "Intro", start: 0.0, end: 60.0 }

- - { title: "Main Topic", start: 60.0, end: 420.0 }

+ - title: "Chapter Title"

+ start: 10.0

+ end: 52.0

+ - title: "Next Chapter"

+ start: 52.0

+ end: 180.0

+ confidence: 0.85

+ source_quality: high

---

- Free-form notes below the frontmatter are fine.

- ```

+ One-paragraph TL;DR of the entire content -- 2-4 sentences, active voice.

- ## Primary Path (agent-driven)

+ ## [00:10] Chapter Title

- ### Parameters (agent choices)

+ Summary paragraphs for this chapter, including key points discussed.

- - `<source>` — caption/transcript file

- - `--output <path>` — default `<source>.summary.md`

- - `--meta <path>` — episode metadata (auto-detected beside source)

- - `--lang <code>` — summary language (default: source language)

- - length — `short` / `medium` / `long` ≈ 200–400 / 500–1000 / 1000–2000 words (default `medium`)

+ > *"Verbatim quote from the transcript, <=40 words"*

- ### Workflow

+ ## [00:52] Next Chapter

- ```bash

- # 1. Build an agent-ready prompt input from the source + meta.md

- python skills/lai-summarize/scripts/prepare.py episode.srt -o prompt_input.md

+ Summary of the next section...

- # 2. Agent reads prompt_input.md and writes summary.md following the schema below.

+ ## Entities

- # 3. Validate frontmatter, chapters, and verbatim quotes

- python skills/lai-summarize/scripts/validate.py episode.srt summary.md

+ - **Person Name** (Person): role or one-line context

+ - **Concept** (Concept): brief explanation

+ - **Organization** (Organization): one-line context

```

- `prepare.py` produces a transcript with `[MM:SS]` timestamps and speaker labels, plus a `# Meta` block that marks `meta.md` chapters as **HARD CONSTRAINT** when present.

+ ## Workflow

- ### Output Schema

+ ### Step 1 -- Read source content

- ```markdown

- ---

- title: "Episode Title"

- seo_title: "SEO title (≤60 chars)"

- seo_description: "One-sentence description (≤160 chars)"

- tags: ["tag1", "tag2"] # 4–8 tags

- chapters:

- - { title: "Chapter Title", start: 10.0, end: 52.0 }

- confidence: 0.85 # 0.0–1.0 self-assessment

- source_quality: high # high | medium | low

- ---

+ Read the transcript/caption file. Supported inputs:

+ - JSON with `supervisions[]` (from alignment/diarization)

+ - SRT, VTT, ASS (subtitle files)

+ - Markdown (Gemini-style transcripts)

+ - Plain text (no timing)

- TL;DR paragraph (2–4 sentences, active voice).

+ Determine:

+ - Total duration and segment count

+ - Whether speakers are labeled

+ - Whether timestamps exist

+ - Source language

- ## [00:10] Chapter Title

- Summary paragraph(s).

+ ### Step 2 -- Gather metadata (optional)

- > *"Verbatim quote, ≤40 words."*

+ If a `.meta.md` file exists alongside the source (or user provides one):

+ - Extract title, channel, speakers, duration

+ - Extract YouTube chapters (if present) -- these become **hard constraints**

- ## Entities

+ **Chapter fidelity rule**: If `meta.md` has chapters, the summary MUST

+ use those exact chapter titles and timestamps. No merging, splitting,

+ reordering, or renaming. The body paragraphs within each chapter are

+ generated by the agent.

- - **Name** (Person|Concept|Organization): one-line context

- ```

+ If no meta.md: the agent generates 1-8 chapters by identifying natural

+ topic shifts.

- ### What `validate.py` checks

+ ### Step 3 -- Generate summary

- - Frontmatter is valid YAML with all required fields

- - `seo_title` ≤ 60, `seo_description` ≤ 160

- - `tags`: 4–8 entries

- - `chapters`: 1–8, each with title/start/end, start < end

- - Hard constraint: chapter titles + timestamps match `meta.md` verbatim when present

- - Body `## [MM:SS] Title` headers match frontmatter chapters 1:1 in order

- - Every `> *"quote"*` appears verbatim in source transcript text

- - `confidence` ∈ [0, 1]; `source_quality` ∈ {high, medium, low}

+ For each chapter:

+ 1. Slice relevant segments by timestamp

+ 2. Identify 1-3 key points

+ 3. Select 1 quotable segment (short, self-contained, thesis-revealing)

+ 4. Write 1-3 summary paragraphs

- Requires `pyyaml` (stdlib `argparse` / `re` otherwise).

+ Additional sections:

+ - **TL;DR**: 2-4 sentence overview at the top

+ - **Entities**: 3-8 entries covering persons, concepts, organizations

- ## Secondary Path (CLI)

+ Quality markers:

+ - `confidence`: 0.0-1.0 self-assessment

+ - `0.9+`: clear domain, clean transcript, hard-constraint chapters

+ - `0.75-0.89`: agent-generated chapters, clear topic flow

+ - `0.5-0.74`: ambiguous segments, speculative chaptering

+ - `source_quality`: `high` / `medium` / `low`

+ - `high`: complete transcript with speakers + clean prose

+ - `medium`: mild ASR errors or missing speaker labels

+ - `low`: heavily noisy transcript

- The CLI takes two positional args (`input`, `output`); there is no `-o`:

+ ### Step 4 -- Validate

+ Before writing output:

+ - [ ] Frontmatter is valid YAML

+ - [ ] Chapter headers match frontmatter `chapters[]` in title and order

+ - [ ] If hard-constraint chapters: all `start`/`end` values match source

+ - [ ] No chapter body is empty

+ - [ ] Every quote appears verbatim in the source transcript

+ - [ ] `tags[]` length between 4 and 8

+ - [ ] `seo_title` <= 60 chars, `seo_description` <= 160 chars

+ ### Step 5 -- Write output

+ Write to `--output` path (default: `<source>.summary.md`).

+ ## Fallback: CLI Summarization

+ For very large files (>500 segments) or when the agent cannot read the

+ entire transcript, fall back to the CLI:

```bash

- lai summarize caption input.json summary.md

+ lai summarize caption input.json -o summary.md

```

- Configure an LLM backend once (required for this path only):

+ ### LLM Configuration for CLI

+ The CLI requires an LLM backend:

```bash

- lai config set summarization.llm.model_name gemini-3-flash-preview

- # Gemini key: see /lai-transcribe

+ # Gemini (recommended -- handles large contexts well)

+ lai config set summarization.llm.model_name gemini-2.5-flash

+ lai config set GEMINI_API_KEY your-key

- # Or OpenAI-compatible:

+ # OpenAI-compatible

lai config set summarization.llm.model_name gpt-4o

- lai config set OPENAI_API_KEY <your-key>

+ lai config set OPENAI_API_KEY your-key

+ # Local model (Ollama, vLLM, etc.)

+ lai config set summarization.llm.model_name qwen3

+ lai config set summarization.llm.api_base_url http://localhost:11434/v1

```

- CLI options: `summarization.lang=zh`, `summarization.length=short`, `summarization.output_format=json`, `meta=video.meta.md`.

+ ### CLI Options

- ## Common Issues

+ ```bash

+ # Basic summary

+ lai summarize caption input.srt

- | Problem | Fix |

- |---------|-----|

- | `validate.py` flags quote not in source | Quote must be verbatim — rewrite or pick another line |

- | Chapter count / timestamp drift from meta.md | Hard constraint — use meta.md values exactly |

- | Transcript too large for the agent | Fall back to CLI (secondary path) |

- | `meta.md` chapters malformed | Remove from meta.md and let the agent generate chapters |

+ # With metadata for richer context

+ lai summarize caption input.json meta=video.meta.md

+ # Chinese summary

+ lai summarize caption input.srt summarization.lang=zh

+ # Short summary

+ lai summarize caption input.srt summarization.length=short

+ # JSON output

+ lai summarize caption input.srt summarization.output_format=json

+ # Custom output path

+ lai summarize caption input.srt output=my_summary.md

+ # Custom LLM endpoint

+ lai summarize caption input.srt \

+ summarization.llm.model_name=qwen3 \

+ summarization.llm.api_base_url=http://localhost:8000/v1

+ ```

+ ## Error Handling

+ | Condition | Action |

+ |-----------|--------|

+ | Source file not found | Fail loud. Check path. |

+ | Empty transcript / no segments | Fail. Not a valid caption file. |

+ | Transcript too large for agent | Fall back to CLI with `lai summarize caption` |

+ | LLM not configured for CLI | Guide user to configure via `lai config set` |

+ | meta.md chapters malformed | Warn, fall back to agent-generated chapters |

+ | Chapter contains 0 segments | Fail. Chapter timestamp split is broken. |

+ | Generated summary fails validation | Fix and retry before writing output |

## Related Skills

- - `/lai-transcribe` — produce the transcript first

- - `/lai-align` — precise timestamps feed chapter boundaries

- - `/lai-diarize` — speaker labels enable speaker-aware summaries

- - `/lai-translate` — translate the summary

+ | Skill | Use When |

+ |-------|----------|

+ | `/lai-transcribe` | Need transcript before summarizing |

+ | `/lai-align` | Need precise timing before summarizing |

+ | `/lai-diarize` | Need speaker labels for richer summaries |

+ | `/lai-translate` | Translate the summary to another language |

+ | `/lai-youtube` | Process YouTube video end-to-end |

+ ### Common Workflow Chains

+ ```bash

+ # Transcribe -> Summarize (agent-driven)

+ lai transcribe run podcast.mp3 transcript.json

+ # Then /lai-summarize for agent-driven summary

+ # Full pipeline: Transcribe -> Align -> Diarize -> Summarize

+ lai transcribe run video.mp4 transcript.json

+ lai alignment align video.mp4 transcript.json aligned.json

+ lai diarize run video.mp4 aligned.json diarized.json

+ # Then /lai-summarize on diarized.json for speaker-aware summary

+ # CLI fallback for large files

+ lai summarize caption huge_transcript.json \

+ meta=video.meta.md \

+ summarization.length=long

+ ```

+ ## Non-Goals

+ - Does NOT transcribe audio -- use `/lai-transcribe`

+ - Does NOT translate summaries -- use `/lai-translate` or a general translation skill

+ - Does NOT generate video chapters for YouTube upload

+ - Does NOT publish summaries to any platform

+ - Does NOT handle non-audio/caption content (articles, documents)