extract-wisdom

Files (13)

• .gitignore
• CLAUDE.md
• SKILL.md
• build-ebook.md · references/
• source-web-text.md · references/
• source-youtube.md · references/
• transcribe.py · scripts/
• wisdom.py · scripts/
• wisdom-epub.css · styles/
• wisdom-index.html · styles/
• wisdom-pdf.css · styles/
• wisdom-pdf.html5 · styles/
• test_frames.py · tests/

SKILL.md (first lines)

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

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

From sammcj/agentic-coding, Apache-2.0.

More from sammcj/agentic-coding