# Enhancing Talks

> 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.

- Skill: `alexanderop/enhancing-talks` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add alexanderop/enhancing-talks`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alexanderop/enhancing-talks/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: alexanderop (https://skillmd.com/u/alexanderop)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alexanderop/enhancing-talks

---


# Enhancing Talk Notes

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

## Workflow Overview

```text
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:
   ```text
   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:

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

This returns structured data:

```json
{
  "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.

```markdown
**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:**

```markdown
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:**

```markdown
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:**

```markdown
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:**

```markdown
> "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:

```markdown
## 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:

```yaml
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:

```markdown
---
(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:

```markdown
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:

```bash
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