source-to-skill

Turn YouTube videos, podcasts, papers, books, articles, and GitHub repos into AI agent skills.

One command in Claude Code, GitHub Copilot CLI, Amp, or any Agent Skills host. Local Whisper, no API keys.

Quick start · Examples · Sources · How it works · FAQ · Website

You watched the two-hour lecture, listened to the podcast, skimmed the paper. A week later your coding agent knows none of it, and pasting the transcript costs the full token bill on every question.

source-to-skill distills any of these into a structured agent skill: a short SKILL.md your agent loads on demand, plus support files it reads only when a question needs them. Answers cite the source, and for video and audio they link back to the exact second (&t=842s).

/source-to-skill https://www.youtube.com/watch?v=zjkBMFhNj_g

intro-to-large-language-models/
├── SKILL.md                         # core ideas + timestamped segment index (1.5k tokens)
├── segments/
│   ├── 01-intro-and-llm-inference.md  # one file per chapter, loaded only when needed,
│   ├── 02-llm-training.md             #   each opening with its &t= deep link
│   └── ...
├── cheatsheet.md                    # numbers, mental models, decision rules
└── source.json                      # lets `/source-to-skill update` refresh it later

Quick start

Claude Code plugin (recommended):

/plugin marketplace add michalstrnadel/source-to-skill
/plugin install source-to-skill@source-to-skill

Any agent, via uv:

uvx --from git+https://github.com/michalstrnadel/source-to-skill source-to-skill install                   # -> ~/.claude/skills/
uvx --from git+https://github.com/michalstrnadel/source-to-skill source-to-skill install --agent copilot   # -> ~/.copilot/skills/ (or: agents)

Once the package is on PyPI this shortens to uvx source-to-skill install.

Manual: git clone this repo and symlink skills/source-to-skill/ into your agent's skills folder (details).

Then install the extractors for the sources you use, and ask:

pip install yt-dlp PyMuPDF        # YouTube + PDFs; EPUB, articles and repos need nothing
pip install mlx-whisper           # podcasts & captionless videos (Apple Silicon)
pip install faster-whisper        #   ... or this one anywhere else

/source-to-skill https://www.youtube.com/watch?v=...      # 1. extract, see the token estimate, pick where to install
/intro-to-large-language-models what is the LLM OS?       # 2. ask - answers cite and deep-link the source

Supported sources

Videos without captions are transcribed with Whisper automatically when a backend is installed (--transcribe forces it).

Examples gallery

Every skill in examples/ was generated by this tool from the linked source. Browse them to see the output quality before installing, or copy one into your skills folder and start asking.

Token counts are estimates (words × 1.33). The agent loads only SKILL.md when the skill is relevant, then opens a segment, chapter, or guide when a question needs it. Asking about Pro Git costs about 1.7k tokens plus one chapter, not 186k.

Why a skill?

Documentation-site scrapers such as Skill_Seekers turn API docs into skills. source-to-skill focuses on what you watch, listen to, and read: talks, courses, podcasts, papers, books, essays.

How it works

flowchart LR
    S["YouTube · podcast · audio file<br/>arXiv / PDF · EPUB · article · repo"] --> X
    subgraph X["Extractor: deterministic Python"]
        D[detect source] --> P[yt-dlp · Whisper · PyMuPDF · stdlib parsers]
    end
    X --> O["full_text.txt<br/>metadata.json<br/>source.json"]
    O --> G
    subgraph G["Generator: your own agent"]
        C[confirm token cost] --> T[distill via the source-type template] --> V[validate]
    end
    G --> K["~/.claude/skills/&lt;slug&gt;/<br/>SKILL.md + on-demand files"]

The work is split in two halves. A deterministic extractor (Python, standard library plus optional yt-dlp, PyMuPDF, and Whisper) normalizes every source into the same text-plus-metadata contract. Your own agent then distills that contract through the template for the source type, following the skill's SKILL.md. Nothing calls a cloud API: transcription runs on your machine, and generation uses whatever model your agent already runs. Details in docs/ARCHITECTURE.md.

Generated skills hold structure, not summaries: frameworks, decision rules, anti-patterns, and concrete numbers, front-loaded into a SKILL.md capped at about 4k tokens. tools/validate_skill.py checks every run: frontmatter, links that resolve, no empty files.

Power features

Topic skills from several sources. Pass several sources and get one skill. Every idea is tagged with the sources behind it ([S1], [S2]), and disagreements.md records where they contradict each other or use different numbers or definitions. Disagreements are kept side by side, never averaged into one claim. See how-transformers-work.

/source-to-skill https://arxiv.org/abs/1706.03762 https://youtu.be/eMlx5fFNoYc https://jalammar.github.io/illustrated-transformer/ how-transformers-work

Skills that stay fresh. Every skill keeps a source.json. When the playlist or channel publishes new videos:

/source-to-skill update ~/.claude/skills/neural-networks-3blue1brown

The tool re-extracts the source, diffs it against the manifest, and generates only the new lessons.

Podcasts and recordings, fully local. Whisper runs on your machine through mlx-whisper on Apple Silicon (whisper-large-v3-turbo by default) or faster-whisper elsewhere. To trade accuracy for speed or disk space, set SOURCE_TO_SKILL_WHISPER_MODEL=mlx-community/whisper-small-mlx (or a faster-whisper size such as base).

Extractor reference

The skill drives this for you. It also works standalone (source-to-skill extract ... from the CLI, or python3 skills/source-to-skill/scripts/extract.py ...):

extract.py <source> [--type youtube|playlist|audio|paper|book|article|repo]
                    [--limit N] [--transcribe] [--work-dir PATH]
extract.py --check

Requirements

• Python 3.10 or newer
• Optional, install only what you use:
  • yt-dlp for YouTube videos, playlists, and channels, and for podcast downloads
  • PyMuPDF for PDF papers and books
  • mlx-whisper (Apple Silicon) or faster-whisper for podcasts, audio files, and captionless videos; mlx-whisper also needs ffmpeg
• EPUB books, web articles, and GitHub repos need only the standard library
• pip install "source-to-skill[all] @ git+https://github.com/michalstrnadel/source-to-skill" installs the CLI with every extractor for your platform

Install for other agents

skills/source-to-skill/ is self-contained (SKILL.md, extractor scripts, validator). Install it with the CLI (source-to-skill install --agent <claude|agents|copilot> [--project], see Quick start), or symlink or copy it into the folder your agent reads:

~/.claude/skills/    # Claude Code
~/.copilot/skills/   # GitHub Copilot CLI
~/.agents/skills/    # Amp / cross-agent

Project-local .claude/skills/, .agents/skills/, or .github/skills/ work too. A symlink picks up git pull updates; a copy stays on the version you copied.

FAQ

Install the plugin, then run /source-to-skill <youtube-url> in Claude Code. The extractor pulls the captions with yt-dlp (or transcribes the audio when there are none), splits them along the video's chapters, and your agent writes a skill whose answers link to the exact timestamp.

Yes. Pass an Apple Podcasts episode link, a direct .mp3 URL, or a downloaded file. With mlx-whisper or faster-whisper installed, the episode is transcribed on your machine and becomes a skill with [hh:mm:ss] citations. Spotify episodes are DRM-protected and not supported.

For learning sources, mostly yes: you get grounded answers about your videos, papers, and books, inside the agent you already code with, as plain files you own. NotebookLM is a hosted notebook. source-to-skill produces portable skills that work in Claude Code, Copilot CLI, Amp, and any Agent Skills host.

/source-to-skill paper.pdf treats a PDF as an academic paper (methods, findings, limitations). For a book, use /source-to-skill book.epub, or add --type book for a PDF book, which takes chapters from the PDF outline.

The tool is free and MIT-licensed. Generation reads the source once through your agent; the skill shows the token estimate and asks before it starts. After that, each question loads a SKILL.md of at most about 4k tokens plus only the files it needs.

No. Extraction and transcription run locally. The only model involved is the one your agent already uses.

A folder with a SKILL.md (a name, a description, and instructions) plus optional files, defined by the open Agent Skills standard. The agent sees only the description until a task needs the skill, then loads it, so skills cost almost nothing while unused.

Troubleshooting

• "No captions available": install a Whisper backend (pip install mlx-whisper or faster-whisper) and re-run; the video is then transcribed locally.
• YouTube errors or "Sign in to confirm you're not a bot": update yt-dlp (pip install -U yt-dlp). --check warns when your copy is over 60 days old.
• "needs ffmpeg": brew install ffmpeg or sudo apt install ffmpeg. mlx-whisper decodes audio through ffmpeg; faster-whisper does not need it.
• Transcription is slow or the model download is too big: set SOURCE_TO_SKILL_WHISPER_MODEL to a smaller model, for example mlx-community/whisper-small-mlx.
• "skipping [NN] ..." on a playlist: those videos had no usable transcript. They are listed under skipped in metadata.json, and the run fails only when every video is skipped.
• A channel extracted only 20 videos: that is the default; pass --limit 50.
• "Couldn't extract a readable article": the page renders with JavaScript or needs a login. Save it as a PDF and pass the file.
• "GitHub returned 404": the repository does not exist or is private; private repos are not supported.
• A watch?v=...&list=... link extracted a single video: that is the default; pass --type playlist for the whole playlist.
• A PDF book parsed as a paper: pass --type book.
• "no usable text layer (scanned PDF?)": run the PDF through OCR first.
• "Missing dependency": run --check and install what it lists.

Roadmap

• OCR for scanned PDFs
• Speaker labels (diarization) for multi-speaker podcasts
• Podcast RSS feeds (whole shows as course skills)
• Skill quality evals: answer accuracy with and without the skill

Ideas and new source types are welcome: open an issue.

Repository layout

skills/source-to-skill/     the installable skill, self-contained
├── SKILL.md                  agent instructions: extract → confirm → generate → verify
├── scripts/extract.py        deterministic extractor (YouTube, audio, arXiv, PDF, EPUB, web, GitHub)
└── tools/                    validate_skill.py, diff_source.py
examples/                   gallery of skills generated by the tool
src/source_to_skill/        CLI package (install / extract / check / validate)
.claude-plugin/             plugin + marketplace manifests
docs/                       architecture, landing page, assets
tests/                      offline test suite, no network

Contributing

Bug reports, new source types, and gallery examples are all welcome. See CONTRIBUTING.md. The test suite runs offline in under a second: pip install -e ".[dev]" && pytest.

If source-to-skill saved you a rewatch, a star helps other people find it.

License

MIT. Cite it with CITATION.cff. Gallery skills are derived from their sources; each one names its source and keeps quotations short.