source-to-skill

A coding agent is excellent at what it already knows and helpless in front of the two-hour lecture you watched last week. The obvious fix — paste in the transcript — is the wrong shape twice over. It's big: a transcript of just 4 962 words is about 6 600 tokens of prose that pushes everything else out of the window. And it's narration, the format least like the answer you want.

What an agent can actually use is structure: the frameworks, the decision rules, the concrete numbers, and a way back to the original when an answer needs checking. That's a different artefact from a summary, and it's exactly what the Agent Skills format is for — instructions the agent loads when the situation calls for them and ignores the rest of the time.

Extraction and distillation are different problems, and the tool refuses to blur them. extract.py detects the source type from the URL or file, runs the matching parser, and writes three things to a work directory: full_text.txt, metadata.json and source.json, the manifest that later lets a skill be refreshed. A recording with no captions is transcribed here too, locally, by whichever Whisper backend is installed. That half is ordinary Python — testable, repeatable, and it either works or tells you why it didn't.

Distillation is the half that needs judgement, so it stays with the agent. SKILL.md tells it what a good skill for this source type looks like; the agent reads the extracted text, confirms the token cost with you first, writes the files and checks the result with validate_skill.py. There's no second model sitting on a server somewhere, because the model is already in the room.

So the 320 tests cover the part that can be tested and don't pretend to cover the part that can't — and every one of them runs without a network connection.

A two-hour lecture with twelve chapters becomes twelve segment files. SKILL.md carries the core ideas and an index of the segments and is capped at about 4 000 tokens — in the examples gallery it lands between 1.1k and 2.0k — and it's the only part the agent pays for by default. A segment file is read only when a question actually lands in its chapter, and cheatsheet.md holds the actionable steps and decision rules, with none of the narration.

Papers keep the shape a paper has — methods.md, findings.md, limitations.md, glossary.md, citations.md — because folding the limitations into a summary is how a paper ends up cited for something it explicitly said it couldn't show. Books keep their chapters. A playlist, a channel or a podcast show becomes a course: a lesson index, one file per video or episode and one cheatsheet across the whole set.

Every segment file opens with a link back to the source at the moment that segment starts. Ask about masking and the answer arrives with &t=668s attached — eleven minutes and eight seconds in, right where the lecturer says it.

Since v0.5 a long chapter is no longer one link: the transcript carries an inline marker every 30 seconds, so a claim links to within half a minute of where it was said, for about 3% more tokens. Podcasts and audio files get the same, with #t= where the origin can seek.

This is what makes the skill trustworthy rather than merely convenient. A distillation is a claim about what the source said, and a claim you can't check in one click is one you end up taking on faith. Papers and articles do the same with their original URL; a repository skill points back to the documentation file it came from.

Pass several sources and you get one topic skill. Every idea carries the sources behind it ([S1], [S2]), and a disagreements.md records where they contradict each other or use different numbers or definitions — side by side, never averaged into one claim. Averaging is what a summary does by default, and it's exactly how a confident wrong answer gets made.

The example in the gallery is “Attention Is All You Need”, 3Blue1Brown's video and Jay Alammar's Illustrated Transformer. They agree on the formula and disagree on things that matter: whether positional encodings are learned or fixed, how sine and cosine are laid out in the vector — and the paper disagrees with itself, quoting 41.8 BLEU in the abstract and 41.0 in the text.

A skill also remembers where it came from. /source-to-skill update re-extracts the playlist or channel, diffs it against the saved source.json and generates only the new lessons.

v0.6.0, two months after v0.4. v0.5 added everything you listen to — podcasts, audio files, captionless videos — plus channels, topic skills, refresh, a CLI package and the examples gallery; v0.6 added whole podcast shows from RSS, tables in books and articles, and repository docs in the order their authors meant. Setup in Claude Code is still two lines, /plugin marketplace add michalstrnadel/source-to-skill and /plugin install source-to-skill@source-to-skill, and the same folder works in GitHub Copilot CLI or Amp, because Agent Skills is an open format.

What isn't done, stated plainly. The package is built and the release workflow is ready, but it isn't on PyPI yet, so the CLI installs with uvx straight from git for now. Scanned PDFs with no text layer still need OCR first, and a multi-speaker podcast has no speaker labels. And the biggest one: I haven't measured whether an agent answers better with a skill than without it. Evals are on the roadmap; until then the evidence is the gallery, which you can read in full.