source-to-skill

One command to turn YouTube videos, playlists, papers, books, web articles, and GitHub repos into agent skills.

This repo is itself an installable agent skill. Install it as a Claude Code plugin (/plugin marketplace add michalstrnadel/source-to-skill) or copy skills/source-to-skill/ into the skills folder your agent reads — see Quick start.

Point it at a source and your coding agent (Claude Code, GitHub Copilot CLI, Amp — any Agent Skills host) distills it into a structured AI agent skill it loads on demand. Video answers deep-link back to the exact &t= timestamp, YouTube playlists become course skills with one linked lesson per video, academic papers (arXiv or PDF) keep their methods/findings/limitations structure, books (EPUB) keep their chapters, web articles boil down to thesis and key claims, and GitHub repositories turn their README and docs into a library guide. Everything runs locally through your own agent — no API keys, no cloud.

Quick start

In Claude Code, install it as a plugin:

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

Or install manually — clone and link the skill folder into the skills folder your agent reads:

git clone https://github.com/michalstrnadel/source-to-skill
ln -s "$PWD/source-to-skill/skills/source-to-skill" ~/.claude/skills/source-to-skill

pip install yt-dlp PyMuPDF   # only what your sources need; EPUB, articles, and repos need neither

1. In Claude Code: /source-to-skill https://www.youtube.com/watch?v=...
2. The agent extracts the source, shows a token estimate, and asks where to install the generated skill.
3. Ask /your-video-slug <question> — the answer cites the transcript and links the exact second of the video.

The same one-liner covers every source type:

/source-to-skill https://www.youtube.com/playlist?list=PL...   # playlist -> course skill
/source-to-skill https://example.com/that-great-blogpost       # article -> claims + highlights
/source-to-skill https://github.com/pallets/flask              # repo docs -> library skill

From a two-hour lecture you get something like:

attention-explained/
├── SKILL.md              # core ideas + timestamped segment index
├── segments/
│   ├── 01-intro.md       # one per video chapter, loaded on demand,
│   ├── 02-self-attention.md   #   each opening with its &t= deep link
│   └── ...
└── cheatsheet.md         # actionable steps and decision rules

Papers and books work the same way — /source-to-skill https://arxiv.org/abs/1706.03762 yields methods.md / findings.md / limitations.md / glossary.md / citations.md; /source-to-skill book.epub yields a chapter index with on-demand chapter files.

Features

• YouTube video → skill — captions via yt-dlp (manual preferred, auto fallback, any language), segmented by the video's own chapters; every segment file deep-links back with &t=.
• YouTube playlist → course skill — the whole playlist becomes a course: lesson index, one lesson file per video opening with a link to that video, one cheatsheet across the course. Captionless videos are skipped with a warning, never fatal.
• Paper → skill — PyMuPDF extraction with academic section detection; arXiv URLs download automatically.
• Book → skill — EPUB parsing with the Python standard library alone; PDF books via --type book take chapters from the document outline.
• Web article → skill — readable-article extraction with the standard library alone (prefers <article>, drops nav/footer/script chrome); any blogpost URL becomes thesis, key claims, and quotable highlights.
• GitHub repo → skill — README and docs/ pulled via one tarball download, no git clone; the repo's documentation becomes a library skill with install steps, usage patterns, and a command cheatsheet.
• Deterministic extractor, agent generator — Python normalizes every source to one text + metadata contract; your agent does the distillation following SKILL.md. Skills are structure (frameworks, decision rules, concrete numbers), not summaries.
• Cheap to query — the generated SKILL.md stays around 4k tokens; segment, lesson, chapter, and findings files load only when a question needs them.

Supported sources

Requirements

• Python ≥ 3.10
• yt-dlp for YouTube videos and playlists, PyMuPDF for PDFs — install only what you use; EPUB books, web articles, and GitHub repos need only the standard library
• Videos need captions (manual or auto-generated); audio transcription is on the roadmap. In a playlist, captionless videos are skipped rather than failing the run
• Scanned PDFs without a text layer are not supported (OCR is on the roadmap)

Check your setup anytime:

python3 skills/source-to-skill/scripts/extract.py --check

Install for other agents

The skill folder skills/source-to-skill/ is self-contained (SKILL.md + extractor scripts + validator). Clone the repo and symlink or copy that folder into the skills 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 keeps git pull updates flowing; a copy freezes the version.

Repository layout

skills/                     the installable skills — start here
└── source-to-skill/        the one skill this repo ships, self-contained:
    ├── SKILL.md              agent instructions: extract → confirm → generate → verify
    ├── scripts/extract.py    deterministic extractor (YouTube, arXiv, PDF, EPUB, web, GitHub)
    └── tools/                validator for generated skills
.claude-plugin/             plugin + marketplace manifests (/plugin install)
docs/                       architecture deep-dive, demo assets
tests/                      offline test suite (182 tests, no network)

Skills this tool generates are not stored here — they install into your own ~/.claude/skills/ (or wherever you choose in step 4). This repo ships exactly one skill: the converter itself.

How it works

Everything lives in the self-contained skill folder skills/source-to-skill/. Its scripts/extract.py detects the source type (YouTube video or playlist URL, arXiv URL, GitHub repository URL, any other web URL as an article, local PDF or EPUB — with an optional --type override), parses it with the matching parser, and writes normalized full_text.txt + metadata.json to a work directory. Your agent then follows the skill's SKILL.md: it confirms the token cost with you, distills the text through the template for that source type, installs the skill where you choose, and validates the result with tools/validate_skill.py. Details in docs/ARCHITECTURE.md.

Troubleshooting

• "No captions available" — the video has no manual or auto captions; transcription isn't supported yet.
• "skipping [NN] ..." warnings on a playlist — videos without captions are skipped and listed under skipped in metadata.json; the playlist fails only when no video has captions.
• "Couldn't extract a readable article" — the page renders its text with JavaScript or requires a login; save it as a PDF and pass the file, or try another URL.
• "GitHub returned 404" — the repository does not exist or is private; check the URL — private repos are not supported.
• A watch?v=...&list=... link extracted a single video — that is the default; pass --type playlist to extract the whole playlist.
• "no usable text layer (scanned PDF?)" — the PDF is image-only; run it through OCR first.
• "Missing dependency" — run python3 skills/source-to-skill/scripts/extract.py --check and install what it suggests.
• A PDF book parsed as a paper — PDFs default to the paper parser; pass --type book to use the book parser with outline chapters.
• Wrong chapters on a PDF book — the PDF has no outline; the parser falls back to heading detection, then full text.

License

MIT