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 pnpm lint:fix && 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:

pnpm lint:fix && 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