extract-wisdom

What this skill does

# Wisdom Extraction

Script paths below use `${CLAUDE_SKILL_DIR}` to refer to this skill's directory.
Default location for Claude Code: `~/.claude/skills/extract-wisdom/`

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

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.

Perform analysis on the content, extracting:

#### 1. Key Insights & Takeaways

- 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

#### 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. 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
- Preserve the original wording exactly, except correct American spellings to Australian English

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

### Step 3: Write Analysis to Markdown File

Determine the output directory:

**YouTube sources:** The renamed directory from Step 2.

**Web and text sources:** The directory created in Step 2 via `create-dir`.

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

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

```bash
uv run ${CLAUDE_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).

Format the analysis using this structure:

```markdown
---
title: "[Title]"
source: "[YouTube URL, web URL, or file path]"
source_type: [youtube|web|text]
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]

**Source**: [YouTube URL, web URL, or file path]

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

**Analysis Date**: AUTO

## Summary

[Brief 2-3 sentence overview of the main topic and purpose]

### Simplified Explanation

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

### Key Takeaways

- [Concise takeaway 1]
- [Concise takeaway 2]
- [Concise takeaway 3]

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

[Any tools, links, git repos or references mentioned in the content]

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

**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
- [ ] 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:

```bash
uv run ${CLAUDE_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:

```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/wisdom.py pdf "<path-to-analysis.md>"
```

The