$npx -y skills add ZeroPointRepo/youtube-skills --skill ytUse when YouTube is relevant: pasted video links or IDs, @handles, quick video lookups, summaries, channel latest uploads, topic search, or any request involving YouTube content — even if YouTube is not mentioned explicitly. Covers transcripts, search, and channel latest. Not for
| 1 | # yt |
| 2 | |
| 3 | Quick YouTube lookup via [TranscriptAPI.com](https://transcriptapi.com). |
| 4 | |
| 5 | ## Setup |
| 6 | |
| 7 | If `$TRANSCRIPT_API_KEY` is not set, read [references/auth-setup.md](references/auth-setup.md) and follow the instructions there to get and store the key. |
| 8 | |
| 9 | ## Required Headers |
| 10 | |
| 11 | Every request needs two headers: |
| 12 | |
| 13 | - **Authorization:** `Bearer $TRANSCRIPT_API_KEY` |
| 14 | - **User-Agent:** your agent's name and version if known (e.g. `HermesAgent/0.11.0`, `ClaudeCode/1.0`). Version is optional — agent name alone is fine. Do not omit this header or send a bare default — Cloudflare will return a 403 (error code 1010) and block the request. |
| 15 | |
| 16 | ## API Reference |
| 17 | |
| 18 | Full OpenAPI spec: [transcriptapi.com/openapi.json](https://transcriptapi.com/openapi.json) — consult this for the latest parameters and schemas. |
| 19 | |
| 20 | ## Transcript — 1 credit |
| 21 | |
| 22 | ```bash |
| 23 | curl -s "https://transcriptapi.com/api/v2/youtube/transcript\ |
| 24 | ?video_url=VIDEO_URL&format=text&include_timestamp=true&send_metadata=true" \ |
| 25 | -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \ |
| 26 | -H "User-Agent: YourAgent/1.0" |
| 27 | ``` |
| 28 | |
| 29 | ## Search — 1 credit |
| 30 | |
| 31 | ```bash |
| 32 | curl -s "https://transcriptapi.com/api/v2/youtube/search?q=QUERY&type=video&limit=10" \ |
| 33 | -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \ |
| 34 | -H "User-Agent: YourAgent/1.0" |
| 35 | ``` |
| 36 | |
| 37 | | Param | Default | Values | |
| 38 | | ------- | ------- | ---------------------- | |
| 39 | | `q` | — | 1-200 chars (required) | |
| 40 | | `type` | `video` | `video`, `channel` | |
| 41 | | `limit` | `20` | 1-50 | |
| 42 | |
| 43 | ## Channel latest — FREE |
| 44 | |
| 45 | ```bash |
| 46 | curl -s "https://transcriptapi.com/api/v2/youtube/channel/latest?channel=@TED" \ |
| 47 | -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \ |
| 48 | -H "User-Agent: YourAgent/1.0" |
| 49 | ``` |
| 50 | |
| 51 | Returns last 15 videos with exact view counts and publish dates. Accepts `@handle`, channel URL, or `UC...` ID. |
| 52 | |
| 53 | ## Resolve handle — FREE |
| 54 | |
| 55 | ```bash |
| 56 | curl -s "https://transcriptapi.com/api/v2/youtube/channel/resolve?input=@TED" \ |
| 57 | -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \ |
| 58 | -H "User-Agent: YourAgent/1.0" |
| 59 | ``` |
| 60 | |
| 61 | Use to convert @handle to UC... channel ID. |
| 62 | |
| 63 | ## Errors |
| 64 | |
| 65 | | Code | Meaning | Action | |
| 66 | | -------- | ---------------- | ---------------------------------------------- | |
| 67 | | 401 | Bad API key | Check key | |
| 68 | | 402 | No credits | transcriptapi.com/billing | |
| 69 | | 403/1010 | Cloudflare block | Add or fix User-Agent header | |
| 70 | | 404 | Not found | No captions or resource doesn't exist | |
| 71 | | 408 | Timeout | Retry once | |
| 72 | |
| 73 | Free tier: 100 credits. Search and transcript cost 1 credit. Channel latest and resolve are free. |