# SkillTube

> Agent-facing counterpart to the [interactive SkillTube Lab](/lab/skilltube/).

## Purpose

SkillTube turns a public YouTube tutorial into one or more draft `SKILL.md`
files for AI agents. It is designed for demonstrated, repeatable digital
workflows: setup procedures, tool operations, coding patterns, automation
sequences, and other processes an agent could plausibly perform again.

It is not a general video summarizer. It should not convert opinions, broad
lessons, entertainment, or unsupported claims into executable instructions.

## Human workflow

1. The visitor submits a public YouTube URL.
2. The server parses and normalizes the URL deterministically and verifies the
   video through YouTube metadata.
3. The server attempts to recover caption text without using a language model.
4. If usable captions are unavailable, the public YouTube URL is supplied to
   Google Gemini's video-understanding interface.
5. Gemini returns candidate repeatable workflows with a title, short
   explanation, prerequisites, expected output, and evidence boundary.
6. The visitor selects at most three candidates.
7. Gemini writes current-format `SKILL.md` drafts for the selected workflows.
8. The visitor can inspect each draft and download one file or a ZIP bundle.

## Generation contract

- Generated skill folders use lowercase kebab-case names.
- YAML frontmatter contains only `name` and `description`.
- The description states what the skill does and when an agent should use it.
- The body uses imperative instructions, prerequisites, validation steps,
  failure handling, and an explicit evidence boundary.
- The source video URL is retained for provenance.
- Missing details must become verification steps, not invented instructions.
- Long transcript passages are neither displayed nor included in the download.
- Every generated artifact is a draft that requires human review before use.

## Limits and enforcement

- Anonymous visitors receive three video analyses per UTC week.
- Each analysis may generate at most three skills.
- Videos are limited to 45 minutes when YouTube exposes their duration.
- A verified analysis attempt that reaches the model consumes one analysis,
  including a valid video with no suitable workflows.
- Provider outages refund the visitor allowance while still counting against
  the site's global safety budget.
- The entire site accepts at most 24 model-backed analysis attempts per UTC day.
- A signed analysis token is bound to its anonymous browser, expires after one
  hour, and can generate exactly one skill bundle. Concurrent and replayed
  generation requests are rejected server-side.
- The server enforces the limit with a random HttpOnly browser identifier and a
  one-way HMAC signature of the requesting network address. Raw network
  addresses are not stored.
- Refreshing the browser does not reset the allowance. Clearing cookies alone
  does not reset the network allowance.
- An anonymous quota cannot be made literally impossible to evade; a different
  browser and network can present as a different visitor. Stronger enforcement
  would require stable authentication.

## Provider choice

The original application used Claude for both workflow discovery and skill
generation after transcript extraction. The Lab edition uses Gemini Flash for
both model stages because Gemini can also inspect a public YouTube URL directly
when captions are missing. This reduces provider count, latency, and operational
cost while preserving the human approval step between discovery and generation.

ChatGPT sign-in is not used. Sites can identify a signed-in ChatGPT user for
identity-aware routes, but a person's ChatGPT subscription is separate from API
usage and cannot be borrowed as this site's model backend.

## Privacy and data flow

- Only public YouTube videos are accepted.
- The submitted URL, extracted captions when available, and selected workflows
  are processed server-side.
- The public URL or captions are sent to Google Gemini to perform the requested
  analysis and generation.
- On Google's free Gemini API tier, submitted content may be used to improve
  Google products. Visitors should submit only public, non-sensitive sources.
- Captions are not returned to the visitor as a transcript.
- The usage database stores anonymous quota hashes, the weekly period, a count,
  and an update timestamp. It does not store the submitted video URL.
- A signed, short-lived analysis token carries the approved candidate metadata
  between discovery and generation.

## Current routes

- Human tool: /lab/skilltube/
- This specification: /lab/skilltube/llm/
- Original project article: /projects/skilltube/
- Original project agent record: /projects/skilltube/llm/
- Lab index: /lab/
- Agent Lab index: /lab/llm/

## API surface

- `GET /api/skilltube/quota` — returns the anonymous weekly allowance.
- `POST /api/skilltube/analyze` — validates a video, discovers candidate
  workflows, consumes one weekly analysis, and returns a signed analysis token.
- `POST /api/skilltube/generate` — accepts a valid analysis token and one to
  three approved workflow identifiers, then returns generated skill drafts.

The endpoints are implementation surfaces for the same-origin Lab interface.
They are not yet a documented public API or a promise of long-term compatibility.