A Claude Code skill that transforms raw podcast/dialogue transcripts into well-structured, scannable Markdown documents.
Add this directory when starting Claude Code so the skill is available globally:
claude --add-dir /path/to/podscriptOr set a shell alias for convenience:
alias claude='claude --add-dir /path/to/podscript'- Automatic speaker identification and label normalization
- Topic-based segmentation with specific, descriptive headings and key insight summaries
- Filler word cleanup while preserving each speaker's distinctive voice
- Inline key quote callouts (💬)
- Opening overview paragraph for quick context
- Table of contents for long transcripts (5+ topic segments)
- Ad reads, sponsor segments, and boilerplate intros/outros are automatically removed
- Supports Chinese, English, and mixed-language transcripts
- Handles transcripts from a few thousand characters to 30,000+
Slash command:
/podscript
Natural language triggers:
- "format this transcript"
- "clean up this podcast"
- "structure this dialogue"
- "格式化这个文字稿"
- "帮我整理这个播客文字稿"
The skill assesses input quality before formatting and handles issues by severity:
| Scenario | Behavior |
|---|---|
| Two speakers, no labels | Proceeds with formatting. Infers speaker roles from contextual cues (Q&A rhythm, knowledge asymmetry, forms of address). Adds a ⚠️ Speaker attribution inferred by AI warning at the top of the output. |
| Three+ speakers, no labels | Stops and asks you to add speaker labels before proceeding — inference accuracy drops significantly with more voices. |
| Garbled text or missing chunks | Reports what it found, offers to proceed with best-effort formatting while flagging unreliable sections. You decide whether to continue. |
Minor issues (typos, inconsistent label formatting like mixing 张三: and 张三：) |
Silently normalizes and proceeds. |
The skill produces a single Markdown document with these components, in order:
- Metadata header — Inferred title + speaker names (e.g.,
**Speakers:** Alex × Jordan) - Opening overview — A 3–5 sentence paragraph summarizing the key themes, formatted as a blockquote
- Table of contents — Auto-generated for transcripts with 5+ topic segments
- Structured body — The transcript broken into numbered topic segments. Each segment includes:
- A specific, descriptive heading (not "About AI" but "AI Is Changing the Standard of Good Design, Not Just the Tools")
- A key insight summary capturing what was argued, not just discussed
- The cleaned dialogue preserving both speakers' voices
- Key quotes — Selectively highlighted inline with
> 💬callouts. Roughly one quote per 3–5 segments.
All structural elements (headings, labels, summaries) match the transcript's language automatically.
What gets cleaned:
- Filler words (
um,uh,you know,嗯,啊,就是说) - False starts and self-corrections where the meaning is clear without them
- Content-free backchannel responses (
right right,yeah yeah,对对对) - Minor grammar smoothing where spoken syntax is confusing in written form
What gets preserved:
- Each speaker's distinctive vocabulary and phrasing
- Meaningful hesitation or self-correction (reveals how someone thinks)
- The back-and-forth rhythm of disagreement or discovery
- Humor, sarcasm, and personality
The line: The reader should feel like they're reading what the speakers would have written if they had time to clean up — not a sanitized summary by a third party.
See the example/ directory for a before/after comparison:
example/input.md— Raw transcriptexample/output.md— Formatted document