Add device-authorized hosted agent skills

.agents/skills/README.md

@@ -0,0 +1,64 @@
+# video2ctx agent skills
+
+Three [Agent Skills](https://agentskills.io) for working with YouTube data — directly from the user's machine, through the hosted HTTP API, or as scheduled monitors. They work in any skills-compatible agent (Claude Code, Codex, Cursor, OpenCode, and others).
+
+| Skill | Reach for it when | Needs |
+| --- | --- | --- |
+| `youtube-direct` | You want stateless YouTube search or extraction directly from the user's machine, with no account, package installation, or hosted dependency | Node.js 18.17+ |
+| `video2ctx-api` | You want the managed, authenticated alternative: supported endpoints, caching, credit accounting, account identity, and usage reads over the hosted API | `video2ctx` CLI plus browser login or an `aty_` API key |
+| `video2ctx-monitoring` | You want the stateful exception: watch a channel, topic, or search for new videos and consume the resulting notifications | `video2ctx` CLI plus browser login or an `aty_` API key |
+
+The split follows real boundaries: `youtube-direct` is a self-contained direct executable with no account; `video2ctx-api` is the managed, authenticated option for stateless hosted discovery, caching, usage, and account boundaries; `video2ctx-monitoring` is the deliberate stateful exception. Most users need only one of the first two data skills.
+
+## Install
+
+List what is available, then install what you need:
+
+```bash
+npx skills add devhims/video2ctx --list
+```
+
+```bash
+npx skills add devhims/video2ctx --skill youtube-direct
+```
+
+Install all three:
+
+```bash
+npx skills add devhims/video2ctx --all
+```
+
+Add `-g` to install globally for your user rather than into the current project, and `-a <agent>` to target a specific agent — for example `-a claude-code -a opencode`. Skip the confirmation prompt with `-y`.
+
+## Authenticate to the hosted service
+
+The two hosted skills use the public `@video2ctx/cli` npm package. Install it once, then authenticate:
+
+```bash
+npm install --global @video2ctx/cli
+video2ctx auth login
+video2ctx whoami --json
+```
+
+The CLI opens video2ctx in the browser, asks the user to approve a short-lived device code, and stores the resulting revocable session in private local configuration. An agent can check the active identity with `video2ctx whoami` and revoke the session with `video2ctx auth logout` without reading or handling the credential itself.
+
+For non-interactive environments, set `VIDEO2CTX_API_KEY` in the process environment. Create a personal key at [the developer dashboard](https://video2ctx.dev/dashboard/developer); never paste it into an agent conversation. CLI sessions and keys carry `data:read` and `account:access` permissions, while API-key management, billing, connected accounts, and account deletion remain browser-only.
+
+## Links
+
+- Product: <https://www.video2ctx.dev>
+- Documentation: <https://docs.video2ctx.dev>
+- OpenAPI 3.1 contract: <https://api.video2ctx.dev/openapi.json>
+- Hosted-service CLI: <https://www.npmjs.com/package/@video2ctx/cli>
+- Optional npm library for application developers: <https://www.npmjs.com/package/all-things-youtube>
+- Source: <https://github.com/devhims/video2ctx>
+
+## License and ownership
+
+Apache-2.0, © the video2ctx authors. See [`LICENSE`](../../LICENSE) at the repository root.
+
+Use of the hosted video2ctx service is additionally governed by its [Terms of Service](https://www.video2ctx.dev/terms) and [Privacy Policy](https://www.video2ctx.dev/privacy). The Apache-2.0 license does not grant permission to use the video2ctx name or branding in ways that imply endorsement. YouTube is a trademark of Google LLC; these skills are not affiliated with or endorsed by Google.
+
+## Contributing
+
+These skills are maintained in the [video2ctx repository](https://github.com/devhims/video2ctx). `youtube-direct` carries its executable; the hosted skills use the independently versioned `@video2ctx/cli` package. Repository-internal guidance lives in `reference/agents/platform-internals.md` instead.

.agents/skills/video2ctx-api/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: video2ctx-api
+description: Managed, authenticated YouTube search and extraction through the production video2ctx hosted API. Use instead of youtube-direct for supported endpoints, managed caching, usage and credit tracking, or account identity. Includes search, browse, transcripts, caption tracks, comments, video details, end screens, channels, and playlists. Requires the video2ctx CLI plus browser login or an aty_ API key; monitoring has its own skill.
+license: Apache-2.0
+---
+
+# video2ctx API
+
+Use the installed `video2ctx` CLI for authenticated requests to `https://api.video2ctx.dev`.
+
+## Check the CLI
+
+Run `video2ctx --version`. When the command is unavailable, explain that this hosted skill requires the public `@video2ctx/cli` npm package and ask the user to approve its installation. After approval, run:
+
+```bash
+npm install --global @video2ctx/cli
+```
+
+Confirm `video2ctx --version` succeeds before continuing. Use that installed command for every request so authentication and versioning stay stable.
+
+## Authenticate
+
+1. Run `video2ctx auth status --json`.
+2. When unauthenticated, run `video2ctx auth login`. Relay the displayed URL and code if the user must continue in a browser. Use `--no-browser` only when opening a browser is unavailable.
+3. Confirm access with `video2ctx whoami --json`.
+
+The login flow stores a revocable CLI session in the user's local config with private file permissions. Keep the session out of prompts, logs, screenshots, and source control. The CLI also accepts `VIDEO2CTX_API_KEY` as a non-interactive fallback and gives it precedence over the stored session. Have the user create and configure a personal key at `https://video2ctx.dev/dashboard/developer` when they prefer that mode; never ask them to paste it into the conversation.
+
+## Make requests
+
+Run public operations through:
+
+```text
+video2ctx api GET '/v1/path?encoded=query' --include-meta
+```
+
+Use `--data '<json>'` only for a documented request body. `--include-meta` returns the response under `data` and settled status, request ID, and credit headers under `meta`.
+
+Before choosing a route, read `https://docs.video2ctx.dev/api/authentication` and `https://docs.video2ctx.dev/api/conventions`. Read the relevant discovery or entity guide, then resolve every remaining method, path, parameter, and response question against `https://api.video2ctx.dev/openapi.json`.
+
+Stay within this skill's surface:
+
+- Search and browse provider content.
+- Read video details, tracks, transcripts, comments, and end screens.
+- Read channel details, channel videos, channel playlists, and playlist contents.
+- Read `GET /v1/usage` and account identity.
+
+Use the provider ID returned by `GET /v1/providers`; the current production provider is YouTube. Monitoring and notifications belong to `video2ctx-monitoring`. Projects, trends, research, imports, exports, billing, API-key management, connected-account changes, account deletion, and administration are outside this skill. Direct the user to `https://video2ctx.dev` for browser-only account actions.
+
+## Preserve response meaning
+
+- Request only the resource or subresource needed.
+- Return continuations only to the endpoint and encoded query that produced them.
+- Treat `comments?all=true` as bounded and newest-first.
+- Inspect `meta.partial` and `meta.warnings` within API data before presenting a result as complete.
+- Use the CLI's finite request deadline. Retry only idempotent reads after transient `429` or `503` responses, with a bounded attempt count and `Retry-After` when present.
+- Branch separately for `401`, `402`, `403`, `422`, `429`, and `503`. Preserve the API error code, request ID, and retry guidance in the user-facing explanation.
+- Read settled credits from `--include-meta`; use `GET /v1/usage` for the current balance and plan limits.
+
+## Done when
+
+The installed CLI reports an authenticated account; every request uses it to target a public production route and remains stateless; no composite or browser-only operation was attempted; partial results and continuations retain their meaning; errors remain classified; and settled credit metadata was observed.

.agents/skills/video2ctx-api/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "video2ctx Hosted API"
+  short_description: "Use managed, authenticated YouTube data"
+  default_prompt: "Use $video2ctx-api to retrieve a YouTube transcript through the hosted video2ctx API."

.agents/skills/video2ctx-monitoring/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: video2ctx-monitoring
+description: Stateful video2ctx monitoring for watching YouTube channels, topics, or searches and receiving new-video notifications. Use for recurring checks, schedules, alerts, delivery preferences, monitor notifications, or video2ctx CLI login. Requires the video2ctx CLI; use video2ctx-api for one-time hosted reads and youtube-direct for direct no-account reads.
+license: Apache-2.0
+---
+
+# video2ctx Monitoring
+
+Use the installed `video2ctx` CLI for authenticated requests to `https://api.video2ctx.dev`.
+
+## Check the CLI
+
+Run `video2ctx --version`. When the command is unavailable, explain that this hosted skill requires the public `@video2ctx/cli` npm package and ask the user to approve its installation. After approval, run:
+
+```bash
+npm install --global @video2ctx/cli
+```
+
+Confirm `video2ctx --version` succeeds before continuing. Use that installed command for every request so authentication and versioning stay stable.
+
+## Authenticate
+
+1. Run `video2ctx auth status --json`.
+2. When unauthenticated, run `video2ctx auth login`. Relay the displayed URL and code if the user must continue in a browser. Use `--no-browser` only when opening a browser is unavailable.
+3. Confirm access with `video2ctx whoami --json`.
+
+The login flow stores a revocable CLI session in the user's local config with private file permissions. Keep the session out of prompts, logs, screenshots, and source control. The CLI also accepts `VIDEO2CTX_API_KEY` as a non-interactive fallback and gives it precedence over the stored session. Have the user create and configure a personal key at `https://video2ctx.dev/dashboard/developer` when they prefer that mode; never ask them to paste it into the conversation.
+
+Read `https://docs.video2ctx.dev/api/authentication`, `https://docs.video2ctx.dev/api/conventions`, and `https://docs.video2ctx.dev/api/monitoring` before operating monitors. Resolve every remaining method, path, parameter, request, and response question against `https://api.video2ctx.dev/openapi.json`.
+
+Run operations through the CLI:
+
+```text
+video2ctx api GET /v1/monitors --include-meta
+video2ctx api POST /v1/monitors --data '<json>' --include-meta
+```
+
+## Define the monitor
+
+1. Confirm the provider with `GET /v1/providers`; the current production provider is YouTube.
+2. Choose `kind`: `channel` uses a channel ID as `target`; `topic` and `search` use search text.
+3. Put human-readable notification context in `query.label` while keeping `target` functional.
+4. Choose `intervalMinutes`: `60`, `360`, `720`, `1440`, `4320`, or `10080`. Use `1440` when the user gives no cadence.
+5. Create exactly the monitor the user requested with `POST /v1/monitors`.
+
+Example body:
+
+```json
+{
+  "provider": "youtube",
+  "kind": "channel",
+  "target": "UC...",
+  "intervalMinutes": 1440,
+  "query": { "label": "Example channel" }
+}
+```
+
+## Operate monitor state
+
+- Treat the first check as a baseline: it records the current leading video and raises no alert. A later leading-video change creates an alert. Creation confirms scheduling; the baseline normally runs about a minute later.
+- Use `GET /v1/monitors` to resolve exact account-owned IDs before `PATCH` or `DELETE`.
+- Change only the requested label, enabled state, or interval with `PATCH /v1/monitors/{id}`. Use `DELETE /v1/monitors/{id}` only for the monitor the user selected.
+- Read matches with `GET /v1/notifications`. Mark one read with `POST /v1/notifications/{id}/read` only after handling the work it triggered.
+- Read and update in-app and email delivery with `GET` and `PUT /v1/notification-preferences`. Email delivery additionally requires the account confirmation flow.
+- Inspect partial metadata and warnings. Preserve API error codes, request IDs, credit metadata, and `Retry-After`. Retry only safe reads or explicitly idempotent operations classified as transient, with a bounded attempt count.
+
+Projects, trends, research, and other composite workflows remain outside this skill. Account deletion, billing, API-key management, connected-account changes, and administration require the browser application.
+
+## Done when
+
+The installed CLI reports an authenticated account; every operation uses it with the live public contract; the provider, kind, target, interval, and label are valid; the baseline behavior is understood; each mutation targets the exact account-owned resource; delivery preferences are respected; notifications are marked read only after handling; and errors, partial results, and settled credit metadata remain visible.

.agents/skills/video2ctx-monitoring/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "video2ctx Monitoring"
+  short_description: "Create and operate video monitor schedules"
+  default_prompt: "Use $video2ctx-monitoring to monitor a YouTube channel for new videos."

.agents/skills/youtube-direct/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: youtube-direct
+description: Direct, no-account YouTube search and extraction from the user's machine. Use for stateless search, transcripts, caption tracks, comments, video details, end screens, channels, and playlists without a video2ctx account, API key, hosted service, or npm installation. Calls YouTube's internal HTTP endpoints directly; use video2ctx-api instead for managed authenticated access, caching, usage, or account identity.
+---
+
+# YouTube Direct
+
+Run the bundled executable for stateless YouTube search and extraction. It sends requests from the user's machine directly to YouTube; it is self-contained and requires Node.js 18.17 or newer.
+
+## Run an operation
+
+Resolve `scripts/youtube.mjs` relative to this `SKILL.md`, then invoke it with Node.js. Use its absolute path when the user's working directory is elsewhere.
+
+```bash
+node <skill-directory>/scripts/youtube.mjs --help
+```
+
+Search before extraction when the user supplied a topic rather than a known resource ID:
+
+```bash
+node <skill-directory>/scripts/youtube.mjs search \
+  --query "agent skills" \
+  --type video \
+  --captions-only
+```
+
+Extract a transcript from a known video:
+
+```bash
+node <skill-directory>/scripts/youtube.mjs transcript \
+  --video-id dQw4w9WgXcQ \
+  --granularity segment
+```
+
+The executable writes one JSON value to stdout. Parse that value and use it to answer the request. Treat stderr as a JSON error payload and branch on `error.code` and `error.retryable`; preserve the classified failure instead of converting it to an empty result.
+
+## Choose the operation
+
+- `search` — videos, channels, or playlists matching a query
+- `tracks` — source caption tracks and translation targets
+- `transcript` — timed transcript segments or words
+- `comments` — one page, or a bounded multi-page collection with `--all --max-pages <n>`
+- `details` — video metadata and availability
+- `endscreen` — interactive end-screen elements
+- `channel-info` — channel identity and public About information
+- `channel-videos` — one Videos-tab page
+- `channel-playlists` — one Playlists-tab page
+- `playlist` — playlist metadata and one video page
+
+Use `--help` as the source of truth for flags and accepted values.
+
+## Bound and verify
+
+- Give pagination an explicit request or page budget. Reuse a continuation only with the same operation and query that produced it.
+- Inspect `meta.partial` and `meta.warnings` whenever the returned resource provides them and the answer implies completeness. `endscreen` returns an array without `meta`.
+- Call `tracks` first when transcript success depends on a particular source or translation language.
+- Use `OUTBOUND_PROXY_URL` for an HTTP(S) proxy when the user's network requires one. Prefer the environment variable over `--proxy` so credentials do not appear in the process list.
+- Expect YouTube's undocumented response shapes and client profiles to change. Report classified upstream failures accurately.
+
+## Keep integration boundaries clear
+
+Use this skill for direct, no-account stateless operations from the user's machine. Use `video2ctx-api` when the user wants the managed hosted API, account or usage operations, caching, or authenticated access. Use `video2ctx-monitoring` for the stateful monitoring exception.
+
+## Done when
+
+The requested local operation completed within an explicit pagination budget; JSON output was parsed; partial-result warnings were reflected where relevant; and any failure retained its error code and retryability.

.agents/skills/youtube-direct/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YouTube Direct — No Account"
+  short_description: "Search and extract directly from YouTube"
+  default_prompt: "Use $youtube-direct to search YouTube directly and extract the selected video's transcript and channel data."