Extract Wisdom

Wisdom Extraction

<skill-dir> in commands below is this skill's base directory, shown when the skill loads.

Workflow

Step 1: Identify Source and Acquire Content

Determine the source type and read the corresponding reference file:

• YouTube URL (contains youtube.com or youtu.be): Read references/source-youtube.md and follow its instructions.
• Web URL or local file: Read references/source-web-text.md and follow its instructions.

Talk slide deck

When the source is a recorded talk or presentation, dispatch a background sub-agent once the output directory exists, then continue to Step 2 without waiting. Brief it to:

1. Find the slide deck for this exact talk: same speaker, title and event. Check links in the source description or page first, then search. A deck from a different delivery of the talk doesn't count.
2. Download it to $TMPDIR and convert it to markdown with the best suited skill or tool available (e.g. pptx-to-md for PPTX, liteparse or pdf for PDF, fetching the page for web-hosted decks). Keep slide order and interpret charts and diagrams.
3. Save it to the output directory as <source-title> - slides.md, with the deck URL on the first line.
4. Return the file path, or "no deck found" with the searches tried.

After acquiring the source content, return here for Step 2. If the user provided additional instructions about the level of detail or focus areas, apply those throughout the analysis.

Step 2: Analyse and Extract Wisdom

IMPORTANT: Avoid signal dilution, context collapse, quality degradation and degraded reasoning for future understanding of the content. Keep the signal-to-noise ratio high. Preserve domain insights while excluding filler or fluff.

Scale the analysis to the source

Length follows what the source carries, never the template.

• Include a section only when it adds claims the reader has not already seen. Drop Structured Breakdown, Insights & Commentary or Additional Resources when they would restate Key Insights or hold nothing.
• Short source (under roughly 1,500 words or 10 minutes of video): write One-Minute Read, Summary, Key Insights and Actionable Takeaways only, plus Notable Quotes when the source has them.
• Finish early rather than pad. When a section runs long, merge related claims and state them more generally.
• The user's instructions on length or focus override these defaults.

Adapt structure to the source shape

• Article or essay: lead with the central claim, group supporting detail by theme.
• Talk, lecture or narrated video: follow the speaker's argument in order, grouping by theme only when the source jumps around.
• Interview or panel: organise by topic and attribute positions to speakers where they differ.
• Discussion thread or comments: synthesise the main viewpoints and the areas of agreement, disagreement, evidence and caveats. Summarising comment by comment or organising around usernames loses the signal.

Perform analysis on the content, extracting:

1. Key Insights

• Identify the main ideas, core concepts, and central arguments
• Extract fundamental learnings and important revelations
• Highlight expert advice, best practices, or recommendations
• Note any surprising or counterintuitive information
• Diagram(s) to explain complex relationships, workflows or concepts

2. Notable Quotes

• Extract memorable, impactful, or particularly well-articulated statements
• Include context for each quote when relevant
• Focus on quotes that encapsulate key ideas or provide unique perspectives
• If the content itself quotes other sources, ensure those quotes are also captured
• If you are adding quotes do not add more than 3-5 quotes unless requested by the user
• Preserve the original wording exactly, except correct American spellings to Australian English

3. Structured Summary

• Create hierarchical organisation of content
• Break down into logical sections or themes
• Provide clear section headings that reflect content structure
• Include high-level overview followed by detailed breakdowns
• Note any important examples, case studies, or demonstrations
• YouTube sources: link each section heading to its moment in the video (see Timestamps below)

4. Actionable Takeaways

• List specific, concrete actions the audience can implement with examples (if applicable)
• Do not add your own advice, input or recommendations outside of what is in the content unless the user has asked you to do so
• Frame as clear, executable steps
• Prioritise practical advice over theoretical concepts
• Include any tools, resources, or techniques mentioned
• Distinguish between immediate actions and longer-term strategies

5. Your Own Insights On The Content

Do this in a separate step, only after you've added the content from the source.

• Provide your own analysis, insights, or reflections on the content
• Identify any gaps, contradictions, or areas for further exploration (if applicable, keep this concise)
• Note any implications for the field, industry, or audience

6. One-Minute Read

Compress the analysis into a section the reader finishes in a minute.

• Open with a 1-2 sentence plain-language explanation of the core concept, then 4-8 bullets, scaled to how much the source carries rather than to a fixed count
• Budget 200 words or fewer for the whole section including the opener, roughly a minute at technical reading speed
• Each bullet states the claim and why it matters, and holds up on its own for a reader who never scrolls further. State the claim here rather than pointing ahead to where it is explained
• Every top-level entry in Key Insights maps to one of these bullets. Merge related insights into a single bullet where they share a through-line, so every claim survives the compression
• When the source carries more than the budget holds, the budget wins: merge further and raise the altitude of each claim rather than dropping a topic or running long

Step 3: Write Analysis to Markdown File

Determine the output directory:

YouTube and fetched web sources: The renamed directory from Step 1.

Local files and WebFetch fallback: The directory created in Step 1 via create-dir.

File name: <source-title> - analysis.md

If a slide deck sub-agent was dispatched in Step 1, wait for its result. When it saved a deck, read it and use it to fill gaps the transcript left: figures, chart data, names, references and URLs the speaker showed but didn't say. List the deck link in Additional Resources.

Before writing the frontmatter, list the existing canonical tags so the new entry can reuse them rather than inventing duplicates:

uv run <skill-dir>/scripts/wisdom.py tags

Choose 3-7 tags that describe the content's themes. Prefer reusing tags already in the corpus over inventing new ones; only add a new tag when no existing tag fits. Tag style: lowercase, hyphenated, prefer singular over plural (agent over agents), and pick one canonical form for abbreviations (rlhf or reinforcement-learning, not both).

Draft every other section first, then compose the One-Minute Read from the finished Key Insights and place it at the top when assembling the file.

Format the analysis using this structure:

---
title: "[Title]"
sources:                                       # one or more; each URL on its own bullet line
  - "[YouTube URL, web URL, or file path]"
source_type: [youtube|web|text]                # type of the primary (first) source
author: "[Author, speaker, or channel name]"
content_date: [YYYY-MM-DD]                    # Optional: only if the content's publication date is known
description: "[1-3 sentence summary suitable for sharing on Slack. Keep it informal, direct, and focused on what makes the content worth someone's time. Include the core concept and why it matters.]"
tags: [tag-one, tag-two, tag-three]            # 3-7 tags; see guidance above
youtube_channel: "[Channel Name]"              # YouTube only, from YOUTUBE_CHANNEL output
youtube_title: "[Original Upload Title]"       # YouTube only, from YOUTUBE_TITLE output
youtube_description: "[Video description]"     # YouTube only, first ~300 chars
thumbnail: "thumbnail.jpg"                     # Auto-set if downloaded; "false" to hide, "placeholder" for gradient
---

# Analysis: [Title]

**Sources**: [source URL; for more than one, list each on its own bullet line below]

**Content Date**: [YYYY-MM-DD]

**Analysis Date**: AUTO

## One-Minute Read

[Explain It Like I'm 18: A simple 1-2 sentence explanation of the core concept in a way an 18 year old could understand]

- [Claim 1, and why it matters]
- [Claim 2, and why it matters]
- [Claim 3, and why it matters]
- etc..

## Summary

[2-3 sentences on the source itself: what kind of content this is, its scope, and the author's aim]

## Key Insights

- [Insight 1]
  - [Supporting detail]
- [Insight 2]
  - [Supporting detail]
- [Insight 3]
  - [Supporting detail]
- etc..

---

## Structured Breakdown

### [Section 1 Title]

[Content summary]

### [Section 2 Title]

[Content summary]

## Actionable Takeaways

1. [Specific action item 1]
2. [Specific action item 2]
3. ...

## Insights & Commentary

[Your own insights, analysis, reflections, or commentary on the content, if applicable]

## Notable Quotes (Only include if there are notable quotes)

> "[Quote 1]"

Context: [Brief context if needed]

> "[Quote 2]"

Context: [Brief context if needed]

---

## Additional Resources

- [Resource name](https://url): one-line summary

_Wisdom Extraction: [Current date in YYYY-MM-DD]_

Keep the section roles distinct so the reader's minute buys four different things:

• One-Minute Read: the compressed claims, standing alone
• Summary: what kind of source this is, its scope and the author's aim
• Key Insights: the full set of claims, each with the mechanism or evidence behind it
• Structured Breakdown: the walk-through, section by section

Date fields:

• content_date and Content Date are optional, only include them if you can determine when the content was originally published from the source material.
• Do NOT write the date frontmatter field. The script stamps it automatically during PDF export.
• Always write **Analysis Date**: AUTO in the body. The script replaces AUTO with the actual local date during PDF export.

After writing the analysis file, inform the user of the location.

Step 4: Critical Self-Review

Conduct a critical self-review of your summarisation and analysis.

Create tasks to track the following (mechanical checks first, then content quality):

• No American English spelling - check and fix (e.g. judgment->judgement, practicing->practising, organize->organise)
• No em-dashes, double-dashes, smart quotes, or non-standard typography
• Proper markdown formatting
• One-Minute Read is within 200 words and every top-level Key Insight maps to one of its bullets (merged bullets are fine)
• YouTube: every timestamp link matches a marker in the transcript and is no later than DURATION
• No section restates another; for sources over roughly 1,500 words the analysis is shorter than the source
• Accuracy & faithfulness to the original content
• Completeness
• Concise, clear content with no fluff or marketing speak that maintains a high signal-to-noise ratio with no filler content
• Logical organisation & structure

Re-read the analysis file, verify each item, fix any issues found, then mark tasks completed.

After completing your review and edits, format the markdown:

uv run <skill-dir>/scripts/wisdom.py format "path/to/file.md"

Step 5: PDF Export

After all content is created and reviewed, render the markdown analysis to a styled PDF for easier sharing with the following command:

uv run <skill-dir>/scripts/wisdom.py pdf "<path-to-analysis.md>"

The PDF is saved alongside the markdown file with a .pdf extension. Use --open to open it after rendering, or --css <file> to provide an alternative stylesheet.

After PDF export, regenerate the wisdom library index to include the new entry:

uv run <skill-dir>/scripts/wisdom.py index

Step 6: Surface The One-Minute Read And Sharing Blurb

Output both of these to the conversation, in this order:

1. The ## One-Minute Read section, verbatim from the analysis file, so the user gets the fast read without opening anything.
2. The frontmatter description field as a plain text message suitable for sharing the source on Slack. If it needs improvement at this stage, update the frontmatter first. Plain text, no markdown formatting, no bullet points.

Then stop unless further instructions are given.