source-to-skill

Turn YouTube videos, podcasts, papers, books, docs sites, and your own notes into AI agent skills.
One command in Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Amp, or any Agent Skills host. Answers link to the exact second. Local Whisper, no API keys.

Quick start · Examples · Sources · Study & eval · How it works · FAQ · Website

You watched the two-hour lecture, listened to the podcast, skimmed the paper, sat through the planning call. 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
├── evals/evals.json                 # grounded questions to score the skill against its source
└── 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

As a plugin the commands are namespaced: /source-to-skill:source-to-skill, /source-to-skill:skill-study, and so on. Plain requests ("turn this video into a skill") load the right skill on their own.

Codex, Cursor, Gemini CLI, Copilot, Amp, OpenCode, and other agents, with the skills CLI:

npx skills add michalstrnadel/source-to-skill

Or with uv, which also gives you the source-to-skill CLI:

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 codex   # -> ~/.agents/skills/

--agent takes claude, agents/codex, copilot, gemini, cursor, opencode, kiro, windsurf, or factory; add --project to install into the current repo. 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; asking about uv costs 1.7k plus one guide, not 244k.

Study, test and manage your skills

The plugin ships three companion skills that work on anything source-to-skill made:

Measured, not claimed

Every generated skill ships evals/evals.json (the skill-creator format): questions drafted from the original source while it is in context, each with checkable expectations. For the gallery, an agent holding only the skill answered questions drafted from each re-extracted source:

Questions and per-expectation results live in each example's evals/ folder. The questions were written by the same project that wrote the skills, so treat the score as a regression check, not an independent benchmark. The plugin itself is tested with claude plugin eval: 12 cases check that the right skill loads for real requests and stays out of unrelated ones.

Why a skill?

Documentation-site scrapers such as Skill_Seekers turn API docs into skills, and book-to-skill does books. source-to-skill focuses on what you watch, listen to, and discuss: talks, courses, podcasts, meetings and threads, with links to the exact second, alongside papers, books, docs and your own notes.

How it works

flowchart LR
    S["YouTube · podcast · audio · meeting .vtt<br/>arXiv / PDF · EPUB · article · repo<br/>llms.txt docs · notes · .docx/.pptx · HN/Reddit"] --> 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|
                           docs|notes|document|thread|transcript]
                    [--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, GitHub repos, docs sites, notes folders, Word/PowerPoint files, threads, and .srt/.vtt transcripts 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

Each folder in skills/ is self-contained (source-to-skill/ carries the extractor and validator). npx skills add michalstrnadel/source-to-skill or source-to-skill install --agent <name> [--project] puts all four in place; --only installs just source-to-skill. Or symlink or copy the folders yourself:

Cursor, Gemini CLI, Copilot and OpenCode also read ~/.agents/skills/, so one install there covers several agents. A symlink picks up git pull updates; a copy stays on the version you copied.

FAQ

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.
• --check says a Whisper backend is "BROKEN": it is installed but its native libraries fail to load (often a wheel built for another OS release); reinstall it or use another Python version.
• "no llms.txt found": the docs site publishes neither llms-full.txt nor llms.txt. Pass a single page as an article, or the docs' GitHub repo.
• Reddit answers HTTP 403: some networks block anonymous access to Reddit's JSON. Try another network, or print the thread to PDF and pass it with --type book.
• ".doc / .ppt is not supported": open the file and save it as .docx / .pptx first.

Roadmap

• OCR for scanned PDFs
• Speaker labels (diarization) for multi-speaker podcasts
• An MCP server exposing extraction to agents without shell access
• Independent eval questions for the gallery, written by people who have not seen the skills

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,
│                               llms.txt docs, notes, Office files, HN/Reddit, .srt/.vtt)
└── tools/                    validate_skill.py, diff_source.py
skills/skill-study/         quizzes, spaced repetition, Anki export
skills/skill-eval/          blind, grounded scoring of a generated skill
skills/skill-library/       inventory, search and refresh of every skill you made
evals/                      claude plugin eval suite: does the right skill load
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.