enhancing-talks

name	enhancing-talks
description	Enhance talk notes with Blinkist-style summaries and timestamps. Use when asked to "enhance talk", "improve talk notes", "add timestamps", "blinkist-style talk summary", or "make talk notes better". Adds Core Message, Key Insights with timestamps, Talk Structure, Notable Quotes, Who Should Watch, and Action Items via transcript analysis.
allowed-tools	Read, Write, Edit, Bash, WebFetch, Glob, Grep, Task, TaskOutput, WebSearch, AskUserQuestion

Enhancing Talk Notes

This skill transforms basic talk notes into Blinkist-style summaries with timestamped insights, talk structure, and actionable takeaways.

Workflow Overview

Phase 1: Talk Identification
   └─ Find and validate talk note

Phase 2: Transcript Acquisition
   └─ Fetch timestamped transcript (JSON format)

Phase 3: Parallel Analysis (4 agents)
   ├─ Agent 1: Key insights from transcript chunks
   ├─ Agent 2: Talk structure & section boundaries
   ├─ Agent 3: Notable quotes with timestamps
   └─ Agent 4: Audience, prerequisites & action items

Phase 4: Content Synthesis
   ├─ Core Message (1-2 sentences)
   ├─ Key Insights (8-12 timestamped blinks)
   ├─ Talk Structure (chapter-style overview)
   ├─ Notable Quotes (3 quotes with timestamps)
   ├─ Who Should Watch
   └─ Action Items

Phase 5: User Review (BLOCKING GATE)
   └─ Present content, await approval

Phase 6: Save Enhanced Note
   └─ Insert sections, preserve original

Phase 7: Quality Check
   └─ Run vp check && pnpm typecheck

---

Phase 1: Talk Identification

1.1 Find the Talk Note

Accept a talk slug, title, or partial name as argument:

1. Try exact slug match first: Check if content/{slug}.md exists (convert spaces to hyphens, lowercase)
2. If no exact match: Use Grep to search for the title in talk notes:

   Grep pattern: "title:.*{search term}" with glob: "content/*.md"
   

3. Filter to talks only: Read matching files and verify type: talk in frontmatter

Outcomes:

• Single match → proceed with that file
• Multiple matches → list options for user to choose
• No match → list available talks with type: talk

1.2 Validate and Extract

Read the note and verify:

1. Frontmatter has type: talk
2. Has required fields: title, url, authors

Extract and store:

• URL: YouTube video URL for transcript fetching
• Frontmatter: title, authors, conference, summary
• Opening paragraph: First paragraph before any ## heading
• Body sections: All content from first ## heading onwards

If not a talk, inform user this skill only works on talk notes.

---

Phase 2: Transcript Acquisition

2.1 Fetch Timestamped Transcript

Use the enhanced transcript script with JSON format:

python3 .claude/skills/adding-notes/scripts/get-youtube-transcript.py '{url}' --format=json

This returns structured data:

{
  "video_id": "abc123",
  "language": "en",
  "is_generated": true,
  "total_duration": 2700,
  "total_duration_formatted": "45:00",
  "segment_count": 90,
  "segments": [
    { "start": 0.0, "timestamp": "0:00", "duration": 30.5, "text": "..." },
    { "start": 30.5, "timestamp": "0:30", "duration": 28.2, "text": "..." }
  ]
}

2.2 Handle Transcript Failures

If transcript unavailable:

1. Check for manual transcript: --list flag shows available options
2. Try alternative language: Use --lang flag
3. Fall back to web research: Switch to WebSearch-based analysis (like enhancing-notes)

Store transcript data for parallel agent processing.

---

Phase 3: Parallel Analysis

Spawn 4 agents in parallel to analyze the transcript:

Agent Configuration

Read references/chunking-strategy.md and references/insight-extraction.md before spawning agents.

**Agent 1 - Key Insights:**
Task tool with subagent_type: "general-purpose"
prompt: |
Analyze this talk transcript to extract 8-12 key insights.

TRANSCRIPT (with timestamps):
{timestamped_transcript}

For each insight:

1. Identify a specific, standalone idea (not vague)
2. Note the timestamp where it's discussed
3. Write 2-3 sentences explaining with concrete detail
4. Use bold title format

Output format for each insight:
**[Insight Title]** (MM:SS) - [2-3 sentence explanation with specific examples or data from the talk]

Guidelines from references/insight-extraction.md:

- Each insight must be self-contained and valuable alone
- Include concrete examples, data, or frameworks mentioned
- Progress from foundational to advanced concepts
- Avoid generic statements like "the speaker emphasizes the importance of X"

**Agent 2 - Talk Structure:**
Task tool with subagent_type: "general-purpose"
prompt: |
Analyze this transcript to identify the talk's structure.

TRANSCRIPT (with timestamps):
{timestamped_transcript}

Identify 4-7 major sections with:

1. Section title (descriptive, 2-4 words)
2. Starting timestamp
3. Brief description (1 sentence)

Look for:

- Introduction/opening hook
- Major topic transitions
- Key examples or stories
- Conclusion/call to action

Output format:

1. **[Section Title]** (MM:SS) - [One sentence description]
2. **[Section Title]** (MM:SS) - [Description]
   ...

**Agent 3 - Notable Quotes:**
Task tool with subagent_type: "general-purpose"
prompt: |
Extract the 3 most powerful, quotable moments from this talk.

TRANSCRIPT (with timestamps):
{timestamped_transcript}

Selection criteria:

- Captures the talk's core philosophy
- Memorable and shareable phrasing
- Represents different aspects of the talk
- Surprising insight or contrarian view

For each quote:

1. Extract the exact words (clean up filler words if needed)
2. Note the timestamp
3. Keep under 40 words each

Output format:

> "Quote text here." (MM:SS)

> "Second quote here." (MM:SS)

> "Third quote here." (MM:SS)

**Agent 4 - Audience & Actions:**
Task tool with subagent_type: "general-purpose"
prompt: |
Analyze this talk to identify the target audience and actionable takeaways.

TRANSCRIPT (with timestamps):
{timestamped_transcript}

TALK INFO:
Title: {title}
Speaker: {author}
Conference: {conference}

Generate:

1. WHO SHOULD WATCH (1-2 paragraphs):
   - Professional context (developers, designers, managers, etc.)
   - Problems they're trying to solve
   - What they'll gain from watching
   - Any prerequisites or background knowledge needed

2. ACTION ITEMS (3-5 concrete actions):
   - Specific, actionable next steps viewers can take
   - Based on explicit or implicit recommendations in the talk
   - Checkbox format: - [ ] Action item

Output format:

## Who Should Watch

[1-2 paragraphs]

## Action Items

- [ ] First action
- [ ] Second action
      ...

Collect all results via TaskOutput (blocking).

Writing Style Reference

Before generating content, read .claude/skills/writing-style/SKILL.md for the full writing guidelines. Key points:

• Active voice: "The speaker argues..." not "It is argued..."
• No boilerplate: Jump straight to insights, no "This talk explores..."
• End with emphasis: Put the key point at the end of sentences
• Everyday words: "use" not "utilize", "help" not "facilitate"
• No vague pronouns: Name the thing, don't say "this leads to that"

---

Phase 4: Content Synthesis

Using transcript analysis results, generate six new sections:

4.1 Core Message

Write the talk's thesis in 1-2 sentences:

• Capture the central argument or insight
• Be concise (under 50 words)
• Make it memorable and quotable

Example:

Local-first software must survive not just network outages, but the complete disappearance of its creators. The key is commoditized sync infrastructure with open protocols.

4.2 Key Insights

Compile 8-12 numbered insights from Agent 1:

Format:

1. **[Insight Title]** (12:34) - [2-3 sentence explanation with specific detail]

Guidelines:

• Each insight should be standalone and valuable
• Timestamp links to the moment in the video
• Include concrete examples or data when mentioned
• Progress from foundational to advanced concepts
• Avoid generic statements - be specific

Example:

1. **CRDTs Are Necessary But Not Sufficient** (8:45) - Skiff, built on yjs CRDTs, still shut down when Notion acquired it. Technology alone doesn't guarantee resilience—the entire application architecture must be built for independence.

2. **Self-Hosting Isn't the Answer** (15:22) - Self-hosting requires technical skills most users lack, and even skilled users don't want to run servers. It's a partial solution at best for the local-first vision.

4.3 Talk Structure

Compile section overview from Agent 2:

Format:

1. **Introduction** (0:00) - Sets up the problem of cloud dependency
2. **Historical Context** (4:30) - Traces local-first from CRDTs to today
3. **Case Studies** (12:00) - Examines Skiff and other failures
4. **The Solution** (25:00) - Proposes commoditized sync infrastructure
5. **Q&A** (40:00) - Addresses audience questions

4.4 Notable Quotes

Select 3 quotes from Agent 3:

Format:

> "Quote text here." (12:34)

> "Another powerful quote." (23:45)

> "Third memorable quote." (34:56)

Clean blockquotes with timestamps, no attribution needed (speaker is in frontmatter).

4.5 Who Should Watch

Use Agent 4's audience analysis (1-2 paragraphs):

• Professional context
• Problems they're trying to solve
• What they'll gain
• Prerequisites if any

4.6 Action Items

Use Agent 4's actionable takeaways:

• 3-5 concrete next steps
• Checkbox format for actionability
• Based on talk recommendations

---

Phase 5: User Review (BLOCKING GATE)

This is a mandatory approval step. Present the generated content to the user before saving.

5.1 Present Content

Display the six generated sections in a formatted preview:

## Preview of Enhanced Content

### Core Message

[Generated core message]

### Key Insights

[Generated 8-12 timestamped insights]

### Talk Structure

[Generated section overview]

### Notable Quotes

[3 timestamped quotes]

### Who Should Watch

[Generated audience description]

### Action Items

[Generated action items]

5.2 Request Approval

Use the AskUserQuestion tool:

question: "Does this enhancement look good?"
header: "Review"
multiSelect: false
options:
  - label: "Save"
    description: "Add these sections to the talk note"
  - label: "Regenerate"
    description: "Try again with different focus"
  - label: "Edit"
    description: "Tell me what to change"
  - label: "Cancel"
    description: "Don't modify the note"

5.3 Handle Response

• Save: Proceed to Phase 6
• Regenerate: Return to Phase 3 with modified prompts
• Edit: Apply user feedback, show updated preview
• Cancel: Exit without changes

Do NOT proceed to Phase 6 without explicit user approval.

---

Phase 6: Save Enhanced Note

6.1 Structure the Enhanced Content

Insert new sections after the opening paragraph, before existing headings:

---
(existing frontmatter unchanged)
---

(existing opening paragraph preserved)

## Core Message

[Generated core message]

## Key Insights

1. **[Title]** (timestamp) - [Explanation]
2. **[Title]** (timestamp) - [Explanation]
   ...

## Talk Structure

1. **[Section]** (timestamp) - [Description]
2. **[Section]** (timestamp) - [Description]
   ...

## Notable Quotes

> "Quote 1 here." (timestamp)

> "Quote 2 here." (timestamp)

> "Quote 3 here." (timestamp)

## Who Should Watch

[Generated audience description]

## Action Items

- [ ] Action 1
- [ ] Action 2
- [ ] Action 3

---

(original body content preserved below)

## [Original sections]

...

6.2 Preserve Original Content

Critical: Never delete existing content:

• Keep all frontmatter fields
• Keep opening paragraph
• Keep all original ## sections and their content
• Keep all wiki-links [[slug]]

The --- separator clearly divides generated content from original notes.

6.3 Write the File

Use the Edit tool to insert the new sections at the correct position.

6.4 Confirmation

Report to user:

Saved: content/{slug}.md

- Core Message: [word count] words
- Key Insights: [count] timestamped insights
- Talk Structure: [count] sections
- Notable Quotes: 3 quotes
- Who Should Watch: added
- Action Items: [count] items
- Original content: preserved

---

Phase 7: Quality Check

Run linter and type check to catch any issues:

vp check && pnpm typecheck

If errors are found, fix them before completing the task.

---

Error Recovery

Error	Recovery
Talk not found	List available talks with type: talk
Not a talk type	Inform user skill only works on talks
Transcript unavailable	Fall back to WebSearch analysis
Agent analysis fails	Retry with simplified prompts
User rejects content	Allow regeneration with feedback
No insights extracted	Try broader analysis or web research

---

Quality Checklist

Before saving, verify:

• Talk note exists and has type: talk
• Transcript was fetched (or web research fallback used)
• Core Message is under 50 words
• Generated 8-12 Key Insights with timestamps
• Each insight has bold title, timestamp, and explanation
• Talk Structure has 4-7 sections with timestamps
• 3 notable quotes with timestamps included
• Who Should Watch section is present
• Action Items has 3-5 concrete items
• Original content preserved
• User explicitly approved changes
• Markdown formatting is valid