SKILL.md- the skill, written out in plain English

criteria:
  - name: youtube_api_calls_logged
    kind: deterministic
    check: "Verify all calls to the YouTube Data API v3 are logged in 'state/log/pending-eval.ndjson' with appropriate input parameters."
  - name: required_inputs_present
    kind: deterministic
    check: "Check that the 'getComments_input', 'replyToComment_input', and 'uploadVideo_input' fields are present and not null when the corresponding function is invoked."
  - name: youtube_function_completeness
    kind: judge
    check: "Assess if the executed YouTube function (e.g., getComments, uploadVideo) produced the expected and complete output as defined by the YouTube Data API v3 specifications."
  - name: no_unhandled_exceptions
    kind: deterministic
    check: "Ensure the execution completes without any unhandled exceptions or errors logged in the system, indicating stable operation."
  - name: correct_api_endpoint_used
    kind: judge
    check: "Confirm that the skill utilized the correct YouTube Data API v3 endpoints for the requested operation, adhering to the API documentation."

AGENTS.md- what the AI loads when this skill comes up

cd ~/projects/snappy-os && npx tsx state/lib/youtube.ts auth

root = Card([
  CardHeader("YouTube Channel"),
  Stack([
    Callout("Channel Stats", [
      Stack([
        TextContent("Subscribers: N,NNN  |  Total Views: N,NNN,NNN  |  Videos: NNN"),
      ], "column")
    ], "info"),
    Callout("Recent Videos", [
      Table(
        ["Title", "Published", "Views", "Likes"],
        [["Video title", "May 14", "1,234", "87"], ...]
      )
    ]),
  ]),
  FollowUpBlock([
    SnappyFollowUpItem("show comments on latest video", "Latest Comments"),
    SnappyFollowUpItem("show most viewed videos", "Top Videos"),
    SnappyFollowUpItem("show engagement rate by video", "Engagement"),
    SnappyFollowUpItem("upload a new video", "Upload"),
  ])
])

root = Card([
  CardHeader("YouTube Comments - <video title>"),
  Stack([
    Callout("Top Comments", [
      Table(["Author", "Comment", "Likes", "Date"], [...rows...])
    ]),
  ]),
  FollowUpBlock([
    SnappyFollowUpItem("reply to top comment", "Reply"),
    SnappyFollowUpItem("show all comments", "All Comments"),
  ])
])

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-youtube/api.ts -- YouTube operations via direct YouTube Data API v3.
 *
 * Read operations (comments, video info, search) use API key auth (GEMINI_API_KEY).
 * Write operations (reply, upload) require YOUTUBE_ACCESS_TOKEN (OAuth2).
 *
 * Obtain YOUTUBE_ACCESS_TOKEN via OAuth2 flow using YOUTUBE_CLIENT_ID +
 * YOUTUBE_CLIENT_SECRET. Analytics requires agent-browser (no API).
 *
 * Usage:
 *   npx tsx api.ts comments <videoId>              # pull comments
 *   npx tsx api.ts reply <commentId> "response"    # reply to a comment
 *   npx tsx api.ts upload <filePath> <title> <description>  # upload video
 *   npx tsx api.ts video <videoId>                 # get video details
 *   npx tsx api.ts search <query>                  # search channel videos
 *
 * Or import as module:
 *   import { getComments, replyToComment, uploadVideo } from "./youtube.ts";
 */

import { env } from "./env.ts";
import { existsSync, readFileSync, realpathSync, writeFileSync } from "fs";

const YT_API = "https://www.googleapis.com/youtube/v3";
const YT_UPLOAD_API = "https://www.googleapis.com/upload/youtube/v3/videos";
const TOKEN_CACHE = `${process.env.HOME}/.claude/skills/snappy-settings/.youtube-token-cache.json`;

interface TokenCache {
  access_token: string;
  refresh_token: string;
  expires_at: number;
}

function loadTokenCache(): TokenCache | null {
  if (!existsSync(TOKEN_CACHE)) return null;
  try { return JSON.parse(readFileSync(TOKEN_CACHE, "utf8")); } catch { return null; }
}

function saveTokenCache(data: TokenCache) {
  writeFileSync(TOKEN_CACHE, JSON.stringify(data, null, 2), { mode: 0o600 });
}

let _accessToken: string | null = null;
let _tokenExpiry = 0;

async function refreshOAuthToken(): Promise<string> {
  if (_accessToken && Date.now() / 1000 < _tokenExpiry - 60) return _accessToken;

  const cached = loadTokenCache();
  if (cached && Date.now() / 1000 < cached.expires_at - 60) {
    _accessToken = cached.access_token;
    _tokenExpiry = cached.expires_at;
    return _accessToken;
  }

  const refreshToken = cached?.refresh_token || env("YOUTUBE_REFRESH_TOKEN", false);
  if (refreshToken) {
    const res = await fetch("https://oauth2.googleapis.com/token", {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        grant_type: "refresh_token",
        refresh_token: refreshToken,
        client_id: env("YOUTUBE_CLIENT_ID"),
        client_secret: env("YOUTUBE_CLIENT_SECRET"),
      }).toString(),
    });
    const data = await res.json() as any;
    if (res.ok && data.access_token) {
      _accessToken = data.access_token;
      _tokenExpiry = Math.floor(Date.now() / 1000) + (data.expires_in || 3600);
      saveTokenCache({
        access_token: data.access_token,
        refresh_token: data.refresh_token || refreshToken,
        expires_at: _tokenExpiry,
      });
      return _accessToken!;
    }
  }

  const staticToken = env("YOUTUBE_ACCESS_TOKEN", false);
  if (staticToken) {
    _accessToken = staticToken;
    _tokenExpiry = Math.floor(Date.now() / 1000) + 3600;
    return _accessToken;
  }

  throw new Error("No YouTube auth. Run: npx tsx api.ts auth");
}

/** API key for read-only operations. */
function apiKey(): string {
  return env("YOUTUBE_API_KEY", false) || env("GEMINI_API_KEY");
}

/** OAuth access token for write operations. */
async function oauthToken(): Promise<string> {
  return refreshOAuthToken();
}

/** GET request with API key auth (read-only). */
async function ytGet(path: string, params: Record<string, string> = {}) {
  const url = new URL(`${YT_API}${path}`);
  url.searchParams.set("key", apiKey());
  for (const [k, v] of Object.entries(params)) {
    url.searchParams.set(k, v);
  }

  const res = await fetch(url.toString());
  if (!res.ok) {
    const text = await res.text().catch(() => "");
    throw new Error(`YouTube GET ${path} failed (${res.status}): ${text}`);
  }
  return res.json();
}

/** POST request with OAuth token (write operations). */
async function ytPost(path: string, body: Record<string, unknown>) {
  const token = await oauthToken();
  const res = await fetch(`${YT_API}${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  if (!res.ok) {
    const text = await res.text().catch(() => "");
    throw new Error(`YouTube POST ${path} failed (${res.status}): ${text}`);
  }
  return res.json();
}

// --- Public API ---

export interface ChannelStats {
  id: string;
  title: string;
  description: string;
  subscriberCount: number;
  viewCount: number;
  videoCount: number;
  thumbnailUrl: string;
}

export interface VideoSummary {
  id: string;
  title: string;
  publishedAt: string;
  viewCount: number;
  likeCount: number;
  commentCount: number;
  thumbnailUrl: string;
}

/**
 * Fetch channel statistics for a channel ID or handle.
 * Defaults to Robert's Snappy channel if no channelId given.
 * Read-only -- uses API key auth.
 */
export async function getChannelStats(channelId?: string): Promise<ChannelStats | null> {
  const params: Record<string, string> = {
    part: "snippet,statistics",
    maxResults: "1",
  };
  if (channelId && channelId.startsWith("@")) {
    params.forHandle = channelId.slice(1);
  } else if (channelId) {
    params.id = channelId;
  } else {
    params.mine = "true";
  }

  let data: any;
  if (params.mine) {
    const token = await oauthToken().catch(() => null);
    if (!token) {
      const key = apiKey();
      const snappyChannelId = "UCXORuV_EuN0_XPXZM1J2o8g";
      delete params.mine;
      params.id = snappyChannelId;
      const url = new URL(`${YT_API}/channels`);
      url.searchParams.set("key", key);
      for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
      const res = await fetch(url.toString());
      data = await res.json();
    } else {
      const url = new URL(`${YT_API}/channels`);
      for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
      const res = await fetch(url.toString(), {
        headers: { Authorization: `Bearer ${token}` },
      });
      data = await res.json();
    }
  } else {
    data = await ytGet("/channels", params);
  }

  const item = data?.items?.[0];
  if (!item) return null;
  return {
    id: item.id,
    title: item.snippet.title,
    description: item.snippet.description,
    subscriberCount: parseInt(item.statistics.subscriberCount || "0", 10),
    viewCount: parseInt(item.statistics.viewCount || "0", 10),
    videoCount: parseInt(item.statistics.videoCount || "0", 10),
    thumbnailUrl: item.snippet.thumbnails?.medium?.url || item.snippet.thumbnails?.default?.url || "",
  };
}

/**
 * List recent videos for a channel with per-video stats.
 * Read-only -- uses API key auth.
 */
export async function listRecentVideos(channelId?: string, maxResults = 8): Promise<VideoSummary[]> {
  const searchData = await ytGet("/search", {
    part: "snippet",
    channelId: channelId || "",
    type: "video",
    order: "date",
    maxResults: String(maxResults),
  }).catch(() => null);

  if (!searchData?.items?.length) return [];

  const ids = searchData.items.map((i: any) => i.id.videoId).join(",");
  const statsData = await ytGet("/videos", {
    part: "statistics,snippet",
    id: ids,
  }).catch(() => null);

  if (!statsData?.items?.length) return [];

  return statsData.items.map((item: any) => ({
    id: item.id,
    title: item.snippet.title,
    publishedAt: item.snippet.publishedAt,
    viewCount: parseInt(item.statistics.viewCount || "0", 10),
    likeCount: parseInt(item.statistics.likeCount || "0", 10),
    commentCount: parseInt(item.statistics.commentCount || "0", 10),
    thumbnailUrl: item.snippet.thumbnails?.medium?.url || "",
  }));
}

/**
 * Pull comment threads for a video.
 * Read-only -- uses API key auth.
 */
export async function getComments(videoId: string, maxResults = 50) {
  return ytGet("/commentThreads", {
    part: "snippet,replies",
    videoId,
    maxResults: String(maxResults),
    order: "time",
  });
}

/**
 * Reply to a YouTube comment.
 * Write operation -- requires YOUTUBE_ACCESS_TOKEN.
 */
export async function replyToComment(commentId: string, text: string) {
  return ytPost("/comments?part=snippet", {
    snippet: {
      parentId: commentId,
      textOriginal: text,
    },
  });
}

/**
 * Upload a video to YouTube.
 * Write operation -- requires YOUTUBE_ACCESS_TOKEN.
 *
 * Uses resumable upload protocol. Reads the file from disk.
 */
export async function uploadVideo(
  filePath: string,
  title: string,
  description: string,
  tags?: string[]
) {
  const token = await oauthToken();

  // Step 1: Initiate resumable upload
  const metadata = {
    snippet: {
      title,
      description,
      tags: tags || [],
      categoryId: "28", // Science & Technology
    },
    status: {
      privacyStatus: "private", // Always upload as private first
      selfDeclaredMadeForKids: false,
    },
  };

  const initRes = await fetch(
    `${YT_UPLOAD_API}?uploadType=resumable&part=snippet,status`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json; charset=UTF-8",
        "X-Upload-Content-Type": "video/*",
      },
      body: JSON.stringify(metadata),
    }
  );

  if (!initRes.ok) {
    const text = await initRes.text().catch(() => "");
    throw new Error(`YouTube upload init failed (${initRes.status}): ${text}`);
  }

  const uploadUrl = initRes.headers.get("location");
  if (!uploadUrl) {
    throw new Error("YouTube upload init did not return a Location header");
  }

  // Step 2: Upload the file
  const fileData = readFileSync(filePath);
  const uploadRes = await fetch(uploadUrl, {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "video/*",
      "Content-Length": String(fileData.byteLength),
    },
    body: fileData,
  });

  if (!uploadRes.ok) {
    const text = await uploadRes.text().catch(() => "");
    throw new Error(`YouTube upload failed (${uploadRes.status}): ${text}`);
  }

  return uploadRes.json();
}

/**
 * Get video details (snippet, statistics).
 * Read-only -- uses API key auth.
 */
export async function getVideo(videoId: string) {
  return ytGet("/videos", {
    part: "snippet,statistics,contentDetails",
    id: videoId,
  });
}

/**
 * Search videos on a channel.
 * Read-only -- uses API key auth.
 *
 * @param query - Search query
 * @param channelId - Channel to search (defaults to Snappy channel)
 */
export async function searchVideos(query: string, channelId?: string, maxResults = 10) {
  const params: Record<string, string> = {
    part: "snippet",
    q: query,
    type: "video",
    maxResults: String(maxResults),
    order: "date",
  };
  if (channelId) params.channelId = channelId;
  return ytGet("/search", params);
}

// --- CLI ---

if ((() => { try { return import.meta.url === `file://${realpathSync(process.argv[1])}`; } catch { return false; } })()) {
  (async () => {
    const [, , cmd, ...args] = process.argv;

    switch (cmd) {
      case "comments": {
        const [videoId] = args;
        if (!videoId) { console.error("Usage: api.ts comments <videoId>"); process.exit(1); }
        const data = await getComments(videoId);
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "reply": {
        const [commentId, ...textParts] = args;
        if (!commentId || !textParts.length) {
          console.error("Usage: api.ts reply <commentId> <text>"); process.exit(1);
        }
        const data = await replyToComment(commentId, textParts.join(" "));
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "upload": {
        const [filePath, title, ...descParts] = args;
        if (!filePath || !title) {
          console.error("Usage: api.ts upload <filePath> <title> <description>"); process.exit(1);
        }
        const data = await uploadVideo(filePath, title, descParts.join(" "));
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "video": {
        const [videoId] = args;
        if (!videoId) { console.error("Usage: api.ts video <videoId>"); process.exit(1); }
        const data = await getVideo(videoId);
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "search": {
        const query = args.join(" ");
        if (!query) { console.error("Usage: api.ts search <query>"); process.exit(1); }
        const data = await searchVideos(query);
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "auth": {
        const { createServer } = await import("http");
        const clientId = env("YOUTUBE_CLIENT_ID");
        const redirectUri = "http://localhost:3142/callback";
        const scopes = "https://www.googleapis.com/auth/youtube https://www.googleapis.com/auth/youtube.force-ssl https://www.googleapis.com/auth/yt-analytics.readonly";
        const state = Math.random().toString(36).slice(2);

        const authUrl =
          `https://accounts.google.com/o/oauth2/v2/auth?` +
          `response_type=code&client_id=${clientId}&redirect_uri=${encodeURIComponent(redirectUri)}` +
          `&state=${state}&scope=${encodeURIComponent(scopes)}&access_type=offline&prompt=consent`;

        console.log("\n=== YouTube OAuth Setup ===");
        console.log("1. Open this URL in your browser:\n");
        console.log(authUrl);
        console.log("\n2. Log in and authorize the app.");
        console.log("3. You'll be redirected back here automatically.\n");
        console.log("Waiting for callback...");

        const { exec } = await import("child_process");
        exec(`open "${authUrl}"`);

        await new Promise<void>((resolve, reject) => {
          const server = createServer(async (req, res) => {
            if (!req.url?.startsWith("/callback")) { res.end(); return; }
            const url = new URL(req.url, `http://localhost:3142`);
            const code = url.searchParams.get("code");
            if (!code) {
              res.writeHead(400); res.end("No code received");
              reject(new Error("No code")); return;
            }
            try {
              const tokenRes = await fetch("https://oauth2.googleapis.com/token", {
                method: "POST",
                headers: { "Content-Type": "application/x-www-form-urlencoded" },
                body: new URLSearchParams({
                  grant_type: "authorization_code",
                  code,
                  redirect_uri: redirectUri,
                  client_id: env("YOUTUBE_CLIENT_ID"),
                  client_secret: env("YOUTUBE_CLIENT_SECRET"),
                }).toString(),
              });
              const tokenData = await tokenRes.json() as any;
              if (!tokenRes.ok) throw new Error(JSON.stringify(tokenData));

              const expiresAt = Math.floor(Date.now() / 1000) + (tokenData.expires_in || 3600);
              saveTokenCache({
                access_token: tokenData.access_token,
                refresh_token: tokenData.refresh_token || "",
                expires_at: expiresAt,
              });

              res.writeHead(200, { "Content-Type": "text/html" });
              res.end("<h1>YouTube auth complete! You can close this tab.</h1>");
              console.log("\nTokens saved! Refresh token:", tokenData.refresh_token ? "YES" : "NO");
              console.log("Token cache:", TOKEN_CACHE);
              server.close();
              resolve();
            } catch (err) {
              res.writeHead(500); res.end("Token exchange failed");
              reject(err);
            }
          });
          server.listen(3142);
        });
        break;
      }
      case "token-status": {
        const cached = loadTokenCache();
        if (!cached) { console.log("No token cache. Run: npx tsx api.ts auth"); break; }
        const now = Date.now() / 1000;
        const remaining = cached.expires_at - now;
        console.log(`Access token: ${cached.access_token.slice(0, 10)}...`);
        console.log(`Refresh token: ${cached.refresh_token ? "present" : "none"}`);
        console.log(`Expires: ${new Date(cached.expires_at * 1000).toISOString()}`);
        console.log(`Remaining: ${remaining > 0 ? Math.floor(remaining / 3600) + " hours" : "EXPIRED"}`);
        console.log(`Status: ${remaining > 0 ? "VALID" : "EXPIRED -- will auto-refresh if refresh token exists"}`);
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [comments|reply|upload|video|search|auth|token-status] ...");
        console.log("\nRead ops (comments, video, search) use API key -- no OAuth needed.");
        console.log("Write ops (reply, upload) use OAuth -- auto-refreshes from token cache.");
        console.log("First time: run 'auth' to bootstrap OAuth tokens.");
    }
  })();
}

scripts- helper scripts it can run

prose-only skill - 1 inline code block live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 10 runs

no recent runs logged - the eval contract is declared but nothing has been graded yet