| name | youtube-to-transcript |
| description | Fetches a YouTube video transcript and returns the text to the user by default. Present the answer like a simple UI — short and substantive; avoid flags, paths, and stack talk unless something breaks or the user asks. Use when the user provides a YouTube link or video ID and wants the transcript; optional save-to-file or Add Knowledge. Triggers on "get transcript", "download transcript", "YouTube transcript", or a YouTube URL plus transcript intent. |
| license | MIT |
| compatibility | **Bun only.** Bundled `scripts/fetch-transcript.ts`. Missing `youtube-transcript-plus` → **only** `bun install -g youtube-transcript-plus` (never a local / project / skill-folder `bun add` or `bun install` without `-g` for this package). Not `npm install -g` either. No `package.json` in the skill. No Node.js / `npx` / `tsx`. If `bun` is not on PATH, fail clearly; do not install Bun in this flow. |
YouTube to Transcript
Default: transcript in the reply; run without --file (stdout = plain text for the user). Do not assume a project folder or transcripts/ unless the user asked.
Save to disk only if the user asked: then --file <path>. No path for a save they want → ask once. Unclear request → default chat only; no extra "reply or file" question.
Optional: --lang xx (default en). Add Knowledge only if they want that next.
How you talk to the user — §6. Do not ask which package to use: always youtube-transcript-plus (see §4).
Workflow
1. URL / ID
Missing → ask once.
2. Output intent
- Chat (default) — no
--file.
- Save — user asked for a file:
--file <path> (ask for path once if needed).
- Unclear — chat only, no
--file.
3. Runtime (Bun only)
bun must be on PATH. If not → stop with error (the user must install Bun; you do not install it here).
Run the script with bun run only, never with node on the .ts file.
4. Dependency (youtube-transcript-plus)
- Check (exit 0 = ok):
bun -e "import('youtube-transcript-plus').then(()=>process.exit(0)).catch(()=>process.exit(1))"
- If the check fails → install only with
bun install -g youtube-transcript-plus. Do not: bun add youtube-transcript-plus in the skill, this repo, or any project; bun install (without -g) to pull this package into a folder. Do not use npm install -g (or pnpm/yarn global) for it. Re-run the check. Do not add a package.json to the skill.
npm / npx / node / NODE_PATH are not used for this skill.
If the import still fails after a successful global install, report the error to the user.
5. Run script
<path> = this skill’s scripts/fetch-transcript.ts — anchor the path to the directory containing this SKILL.md.
- Chat:
bun run <path> "<id-or-url>" [--lang xx]
- Save: add
--file "<path>"
Read stdout = transcript; stderr = progress/errors.
6. Reply (user-facing)
Short, plain language. Do not surface script paths, --lang/--file, or Bun by default. Technical detail when something failed or the user asked.
Normalize HTML entities in text if they appear in the source.
Saved file: one line, human path, if applicable.
Edge cases
- No
bun on PATH — error; do not run.
- No URL — do not run.
- Fetch errors — report; try another
lang / video.
- Relative
--file — resolved vs shell cwd; use an absolute path if the user needs a specific place.
Summary
Bun on PATH, else error → URL/ID (ask if missing) → default chat (or --file if the user wanted a save) → bun -e import check → if needed, bun install -g youtube-transcript-plus (not npm -g) → bun run <script> → answer. One runtime only; no local package files inside the skill.
