Turn a transcript into documentation: $ARGUMENTS
$ARGUMENTS should include:
- A path to a transcript file (e.g.
transcripts/VIDEO_ID.md) OR a glob pattern (e.g. transcripts/*.md)
- Optionally:
--style followed by one of: reference, tutorial, guide, summary, notes (default: reference)
- Optionally:
--output PATH to specify where to save the output
- Optionally:
--title "CUSTOM TITLE" to override the document title
- If no arguments are given, ask the user which transcript to process
Document Styles
| Style |
Purpose |
Structure |
reference |
Comprehensive documentation of all topics covered |
Organized by topic with full detail |
tutorial |
Step-by-step walkthrough if the content is instructional |
Sequential steps with explanations |
guide |
Practical guide extracting actionable advice |
Problem/solution oriented sections |
summary |
Condensed overview of key points |
Executive summary + bullet points |
notes |
Lightly structured study/meeting notes |
Chronological with headers by topic shift |
Before Starting
- Read the transcript file(s) specified in $ARGUMENTS
- If the file has frontmatter (title, video_id, url, duration), capture it for the output metadata
- Read the plain text transcript section (not the timestamped version, if both exist)
- If processing multiple files, process each one independently and save separate outputs
Step 1 — Analyze the Transcript
Read the full transcript and identify:
- Core topics: The 3-8 major subjects or themes discussed
- Key concepts: Definitions, frameworks, models, or terminology introduced
- Actionable items: Steps, recommendations, best practices, or instructions given
- Examples and stories: Concrete illustrations, case studies, or anecdotes used
- Quotes: Memorable or particularly clear statements worth preserving verbatim
- Speakers: If multiple speakers are identifiable, note who said what
- Logical structure: How topics flow and group — this determines your heading hierarchy
Step 2 — Build the Document Structure
Based on the analysis, create a heading outline appropriate to the chosen style:
For reference style:
# Document Title
## Overview (2-3 paragraph summary)
## [Topic 1 Heading]
### [Subtopic if needed]
## [Topic 2 Heading]
...
## Key Takeaways
## Source
For tutorial style:
# Document Title
## Overview
## Prerequisites (if applicable)
## Step 1 — [Action]
## Step 2 — [Action]
...
## Summary
## Source
For guide style:
# Document Title
## Overview
## [Problem/Goal 1]
### Context
### Approach
## [Problem/Goal 2]
...
## Quick Reference
## Source
For summary style:
# Document Title
## Executive Summary (1 paragraph)
## Key Points
## Notable Quotes
## Source
For notes style:
# Document Title
## Overview
## [Topic as discussed — roughly chronological]
## [Next topic shift]
...
## Open Questions / Follow-ups
## Source
Step 3 — Write the Documentation
Transform the raw transcript into polished documentation following these rules:
Content Rules
- Reorganize, don't transcribe — Group related points together even if they were discussed at different times. Documentation should be organized by topic, not by order of speech.
- Clean up spoken language — Remove filler words, false starts, tangents, and repetition. Convert spoken phrasing into clear written prose.
- Preserve meaning precisely — Do not add interpretations, opinions, or information not present in the transcript. If something is ambiguous, note it.
- Keep valuable quotes — When the speaker makes a particularly clear or memorable point, preserve it as a blockquote with attribution.
- Use concrete examples — If the speaker gave examples, include them. They make documentation useful.
- Define terms — If a concept is defined or explained in the transcript, include that definition clearly.
- Add structure — Use bullet lists, numbered steps, tables, and bold key terms to make the document scannable.
Formatting Rules
- Use H2 (
##) for major sections, H3 (###) for subsections. Do not go deeper than H4.
- Use bold for key terms on first mention within a section
- Use blockquotes (
>) for direct quotes from the transcript
- Use code blocks for any technical content (commands, code, configs)
- Use tables when comparing items, listing properties, or presenting structured data
- Keep paragraphs short — 2-4 sentences max
- Use bullet lists for 3+ related items
Step 4 — Add Metadata and Source Attribution
Include frontmatter and a source section:
---
title: "DOCUMENT_TITLE"
source_title: "ORIGINAL_VIDEO_TITLE"
source_url: VIDEO_URL (if available from transcript frontmatter)
source_type: video | audio | transcript
date_processed: TODAY
style: reference | tutorial | guide | summary | notes
---
At the end of the document, add:
---
## Source
- **Original**: [VIDEO_TITLE](VIDEO_URL) (DURATION)
- **Processed**: DATE
- **Style**: reference | tutorial | guide | summary | notes
> This document was generated from a video transcript. Some nuance from the original presentation (tone, visual aids, demonstrations) may not be fully captured.
Step 5 — Save the Output
Save to docs/{slug}.md where slug is derived from the document title (lowercase, hyphens, no stop words). If --output was specified, use that path instead.
Output
After saving, report:
## Documentation Generated
- **Title**: DOCUMENT_TITLE
- **Style**: STYLE
- **Source**: VIDEO_TITLE
- **Sections**: N major sections
- **Word count**: ~N words
- **Saved to**: PATH
Error Handling
- Transcript file not found — List available files in
transcripts/ and ask the user to pick one
- Empty or unreadable transcript — Report the issue; suggest re-extracting with youtube-transcript
- Transcript too short (< 100 words) — Warn the user that the output may be thin; proceed anyway
- Multiple transcripts — Process each independently; report results for each
1---2name: transcript-to-docs3description: Process a video/audio transcript into structured markdown documentation — extracting key topics, organizing into logical sections, and producing a polished reference document.4user-invocable: true5allowed-tools: Read, Write, Edit, Glob, Grep6metadata:7 source: https://skillmd.com/skills/joshuashepherd/transcript-to-docs8---910Turn a transcript into documentation: $ARGUMENTS1112$ARGUMENTS should include:13- A path to a transcript file (e.g. `transcripts/VIDEO_ID.md`) OR a glob pattern (e.g. `transcripts/*.md`)14- Optionally: `--style` followed by one of: `reference`, `tutorial`, `guide`, `summary`, `notes` (default: `reference`)15- Optionally: `--output PATH` to specify where to save the output16- Optionally: `--title "CUSTOM TITLE"` to override the document title17- If no arguments are given, ask the user which transcript to process1819---2021## Document Styles2223| Style | Purpose | Structure |24|---|---|---|25| `reference` | Comprehensive documentation of all topics covered | Organized by topic with full detail |26| `tutorial` | Step-by-step walkthrough if the content is instructional | Sequential steps with explanations |27| `guide` | Practical guide extracting actionable advice | Problem/solution oriented sections |28| `summary` | Condensed overview of key points | Executive summary + bullet points |29| `notes` | Lightly structured study/meeting notes | Chronological with headers by topic shift |3031---3233## Before Starting34351. **Read the transcript file(s)** specified in $ARGUMENTS362. If the file has frontmatter (title, video_id, url, duration), capture it for the output metadata373. Read the plain text transcript section (not the timestamped version, if both exist)384. If processing multiple files, process each one independently and save separate outputs3940---4142## Step 1 — Analyze the Transcript4344Read the full transcript and identify:45461. **Core topics**: The 3-8 major subjects or themes discussed472. **Key concepts**: Definitions, frameworks, models, or terminology introduced483. **Actionable items**: Steps, recommendations, best practices, or instructions given494. **Examples and stories**: Concrete illustrations, case studies, or anecdotes used505. **Quotes**: Memorable or particularly clear statements worth preserving verbatim516. **Speakers**: If multiple speakers are identifiable, note who said what527. **Logical structure**: How topics flow and group — this determines your heading hierarchy5354---5556## Step 2 — Build the Document Structure5758Based on the analysis, create a heading outline appropriate to the chosen style:5960### For `reference` style:61```62# Document Title63## Overview (2-3 paragraph summary)64## [Topic 1 Heading]65### [Subtopic if needed]66## [Topic 2 Heading]67...68## Key Takeaways69## Source70```7172### For `tutorial` style:73```74# Document Title75## Overview76## Prerequisites (if applicable)77## Step 1 — [Action]78## Step 2 — [Action]79...80## Summary81## Source82```8384### For `guide` style:85```86# Document Title87## Overview88## [Problem/Goal 1]89### Context90### Approach91## [Problem/Goal 2]92...93## Quick Reference94## Source95```9697### For `summary` style:98```99# Document Title100## Executive Summary (1 paragraph)101## Key Points102## Notable Quotes103## Source104```105106### For `notes` style:107```108# Document Title109## Overview110## [Topic as discussed — roughly chronological]111## [Next topic shift]112...113## Open Questions / Follow-ups114## Source115```116117---118119## Step 3 — Write the Documentation120121Transform the raw transcript into polished documentation following these rules:122123### Content Rules124125- **Reorganize, don't transcribe** — Group related points together even if they were discussed at different times. Documentation should be organized by topic, not by order of speech.126- **Clean up spoken language** — Remove filler words, false starts, tangents, and repetition. Convert spoken phrasing into clear written prose.127- **Preserve meaning precisely** — Do not add interpretations, opinions, or information not present in the transcript. If something is ambiguous, note it.128- **Keep valuable quotes** — When the speaker makes a particularly clear or memorable point, preserve it as a blockquote with attribution.129- **Use concrete examples** — If the speaker gave examples, include them. They make documentation useful.130- **Define terms** — If a concept is defined or explained in the transcript, include that definition clearly.131- **Add structure** — Use bullet lists, numbered steps, tables, and bold key terms to make the document scannable.132133### Formatting Rules134135- Use H2 (`##`) for major sections, H3 (`###`) for subsections. Do not go deeper than H4.136- Use **bold** for key terms on first mention within a section137- Use blockquotes (`>`) for direct quotes from the transcript138- Use code blocks for any technical content (commands, code, configs)139- Use tables when comparing items, listing properties, or presenting structured data140- Keep paragraphs short — 2-4 sentences max141- Use bullet lists for 3+ related items142143---144145## Step 4 — Add Metadata and Source Attribution146147Include frontmatter and a source section:148149```markdown150---151title: "DOCUMENT_TITLE"152source_title: "ORIGINAL_VIDEO_TITLE"153source_url: VIDEO_URL (if available from transcript frontmatter)154source_type: video | audio | transcript155date_processed: TODAY156style: reference | tutorial | guide | summary | notes157---158```159160At the end of the document, add:161162```markdown163---164165## Source166167- **Original**: [VIDEO_TITLE](VIDEO_URL) (DURATION)168- **Processed**: DATE169- **Style**: reference | tutorial | guide | summary | notes170171> This document was generated from a video transcript. Some nuance from the original presentation (tone, visual aids, demonstrations) may not be fully captured.172```173174---175176## Step 5 — Save the Output177178Save to `docs/{slug}.md` where `slug` is derived from the document title (lowercase, hyphens, no stop words). If `--output` was specified, use that path instead.179180---181182## Output183184After saving, report:185186```187## Documentation Generated188189- **Title**: DOCUMENT_TITLE190- **Style**: STYLE191- **Source**: VIDEO_TITLE192- **Sections**: N major sections193- **Word count**: ~N words194- **Saved to**: PATH195```196197---198199## Error Handling200201- **Transcript file not found** — List available files in `transcripts/` and ask the user to pick one202- **Empty or unreadable transcript** — Report the issue; suggest re-extracting with youtube-transcript203- **Transcript too short** (< 100 words) — Warn the user that the output may be thin; proceed anyway204- **Multiple transcripts** — Process each independently; report results for each