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

criteria:
  - name: ts_api_surface_freshness
    kind: deterministic
    check: "The `state/lib/community.ts` file should contain the functions mentioned in SKILL.md and align with the latest 'snappy-community' kernel API."
  - name: http_api_connectivity
    kind: deterministic
    check: "Invoking a basic read-only function (e.g., listLinks(), listMembers()) from community.ts should successfully connect to the Skool HTTP API and return a non-error response."
  - name: crud_operation_integrity
    kind: judge
    check: "addLink(), updateLink(), and deleteLink() operations should correctly modify the linked resource on the Skool HTTP API as evidenced by subsequent listLinks() calls."
  - name: error_handling_robustness
    kind: judge
    check: "The skill should gracefully handle API errors (e.g., network issues, invalid input) from the Skool HTTP API, logging them appropriately without crashing."

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

echo "[$(date -u +%FT%TZ)] community: <what was missing>" >> state/log/loader-feedback.log

echo "[$(date -u +%FT%TZ)] community: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-community/api.ts -- Skool HTTP API operations for snappy-* skills.
 *
 * IMPORTANT: Skool has NO public API. Most operations (posts, DMs, comments)
 * require agent-browser automation. This module covers ONLY the unofficial
 * api2.skool.com endpoints that work via cookie auth.
 *
 * Usage:
 *   npx tsx api.ts links                    # list sidebar links
 *   npx tsx api.ts add-link "Title" "URL"   # add sidebar link (max 3)
 *   npx tsx api.ts hide-tab classroom       # hide a tab
 *   npx tsx api.ts show-tab calendar        # show a tab
 *
 * Or import as module:
 *   import { listLinks, addLink, hideTab, showTab } from "./community.ts";
 */

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

const SKOOL_API = "https://api2.skool.com";
const GROUP_SLUG = "snappy";
const GROUP_HEX_ID = "f40396161fd74408aa5e28e1e786b330";
const AUTH_STATE = join(process.env.HOME!, ".openclaw/workspace/skool-auth.json");

function loadCookies(): string {
  if (!existsSync(AUTH_STATE)) {
    throw new Error(
      `[snappy-community] Auth state not found at ${AUTH_STATE}. ` +
      `Re-capture by signing in to Skool via agent-browser.`
    );
  }
  const raw = readFileSync(AUTH_STATE, "utf-8");
  const state = JSON.parse(raw);

  // Extract cookies from Playwright-style state file
  const cookies: Array<{ name: string; value: string }> = state.cookies || [];
  return cookies.map((c) => `${c.name}=${c.value}`).join("; ");
}

async function skool(
  path: string,
  options: { method?: string; body?: Record<string, unknown> } = {}
) {
  const { method = "GET", body } = options;
  const cookie = loadCookies();

  const res = await fetch(`${SKOOL_API}${path}`, {
    method,
    headers: {
      Cookie: cookie,
      "Content-Type": "application/json",
    },
    body: body ? JSON.stringify(body) : undefined,
  });

  if (!res.ok) {
    const text = await res.text().catch(() => "");
    throw new Error(`Skool ${method} ${path} failed (${res.status}): ${text}`);
  }

  const contentType = res.headers.get("content-type") || "";
  if (contentType.includes("application/json")) {
    return res.json();
  }
  return { status: res.status, ok: true };
}

// --- Public API ---

/** List sidebar links (max 3 allowed by Skool). */
export async function listLinks() {
  return skool(`/groups/${GROUP_SLUG}/links`);
}

/** Add a sidebar link. Skool returns 422 if you exceed 3. */
export async function addLink(title: string, url: string) {
  return skool(`/groups/${GROUP_SLUG}/links`, {
    method: "POST",
    body: { title, url },
  });
}

/** Update a sidebar link by ordinal (1-indexed). */
export async function updateLink(ordinal: number, title: string, url: string) {
  return skool(`/groups/${GROUP_SLUG}/links/${ordinal}`, {
    method: "PUT",
    body: { title, url },
  });
}

/** Delete a sidebar link by ordinal (1-indexed). */
export async function deleteLink(ordinal: number) {
  return skool(`/groups/${GROUP_SLUG}/links/${ordinal}`, { method: "DELETE" });
}

/** Reorder sidebar links. old is 0-indexed, newPos is 1-indexed (Skool's inconsistency). */
export async function moveLink(oldIndex: number, newIndex: number) {
  return skool(`/groups/${GROUP_SLUG}/move-link`, {
    method: "POST",
    body: { old: oldIndex, new: newIndex },
  });
}

/** Hide a tab (classroom | calendar | map). */
export async function hideTab(tab: "classroom" | "calendar" | "map") {
  return skool(`/groups/${GROUP_HEX_ID}/tabs/${tab}/hide`, { method: "POST" });
}

/** Show a tab (classroom | calendar | map). */
export async function showTab(tab: "classroom" | "calendar" | "map") {
  return skool(`/groups/${GROUP_HEX_ID}/tabs/${tab}/show`, { method: "POST" });
}

/** Update the about body (landing page long description). Max 1000 chars. */
export async function updateAbout(description: string) {
  if (description.length > 1000) {
    throw new Error(`About description exceeds 1000 char limit (got ${description.length})`);
  }
  return skool(`/groups/${GROUP_HEX_ID}/update-landing-page-description`, {
    method: "POST",
    body: { description },
  });
}

/** Update the short description (150-char tagline). */
export async function updateShortDescription(description: string) {
  if (description.length > 150) {
    throw new Error(`Short description exceeds 150 char limit (got ${description.length})`);
  }
  return skool(`/groups/${GROUP_HEX_ID}`, {
    method: "PUT",
    body: { remove_logo: false, remove_logo_big: false, description },
  });
}

// --- Content operations ---
//
// IMPORTANT: Skool's www.skool.com surface is SSR — posts, members, and classroom
// data are shipped inline in the page's __NEXT_DATA__ blob, NOT via XHR to api2.
// Cookie-curl against api2.skool.com/groups/{slug}/posts returns 404 because that
// route doesn't exist on the backend at all. Instead, we drive a real Playwright
// session (via snappy-browse) to the rendered page and read __NEXT_DATA__.
//
// The functions below use the "nextdata" helper which composes:
//   close (fresh session) → open with state → eval(__NEXT_DATA__)

async function nextData(path: string): Promise<any> {
  const { execSync } = await import("child_process");
  const url = `https://www.skool.com${path}`;
  const state = AUTH_STATE;
  // Close any stale daemon so --state is honored, then open.
  try { execSync("agent-browser close", { stdio: "pipe" }); } catch {}
  execSync(`agent-browser --state "${state}" open "${url}"`, { stdio: "pipe", timeout: 30_000 });
  // Wait briefly for hydration
  await new Promise((r) => setTimeout(r, 1500));
  // Base64 to bypass all escaping concerns (content has newlines, quotes, etc.)
  const raw = execSync(
    `agent-browser eval "btoa(unescape(encodeURIComponent(JSON.stringify(__NEXT_DATA__.props.pageProps))))"`,
    { encoding: "utf-8", timeout: 15_000 }
  );
  const b64 = raw.trim().replace(/^"/, "").replace(/"$/, "");
  const json = Buffer.from(b64, "base64").toString("utf-8");
  return JSON.parse(json);
}

/** List community posts (feed). Returns array of post trees with title, content, author. */
export async function listSkoolPosts(page = 1, _limit = 20) {
  const qs = page > 1 ? `?p=${page}` : "";
  const data = await nextData(`/${GROUP_SLUG}${qs}`);
  const trees = data.postTrees || [];
  return {
    total: data.total,
    page: data.page,
    category: data.category,
    posts: trees.map((t: any) => ({
      id: t.post?.id,
      name: t.post?.name,
      title: t.post?.metadata?.title,
      content: t.post?.metadata?.content,
      author: t.post?.user ? `${t.post.user.firstName || ""} ${t.post.user.lastName || ""}`.trim() : null,
      author_id: t.post?.user?.id,
      created_at: t.post?.createdAt,
      like_count: t.post?.metadata?.likesCount,
      comment_count: t.post?.children?.length,
    })),
  };
}

/** LEGACY — api2 posts route does not exist. Use listPosts() instead. */
export async function listPostsLegacy(page = 1, limit = 20) {
  return skool(`/groups/${GROUP_SLUG}/posts?page=${page}&limit=${limit}`);
}

/**
 * Get a single post by SLUG (the `name` field from listPosts, not the id).
 * Returns post metadata + comments tree.
 */
export async function getPost(slug: string) {
  const data = await nextData(`/${GROUP_SLUG}/${slug}`);
  const pt = data.postTree;
  if (!pt) return null;
  const p = pt.post || {};
  return {
    id: p.id,
    name: p.name,
    title: p.metadata?.title,
    content: p.metadata?.content,
    author: p.user ? `${p.user.firstName || ""} ${p.user.lastName || ""}`.trim() : null,
    author_id: p.user?.id,
    created_at: p.createdAt,
    is_pinned: data.isPinned,
    followers: data.followers,
    comments: (pt.children || []).map((c: any) => ({
      id: c.post?.id,
      content: c.post?.metadata?.content,
      author: c.post?.user ? `${c.post.user.firstName || ""} ${c.post.user.lastName || ""}`.trim() : null,
      created_at: c.post?.createdAt,
      reply_count: c.children?.length || 0,
    })),
  };
}

/** LEGACY — direct api2 fetch by id (404s). Kept for reference. */
export async function getPostLegacy(postId: string) {
  return skool(`/groups/${GROUP_SLUG}/posts/${postId}`);
}

/** Create a new community post. */
export async function createSkoolPost(title: string, body: string, category?: string) {
  return skool(`/groups/${GROUP_SLUG}/posts`, {
    method: "POST",
    body: { title, body, ...(category ? { category } : {}) },
  });
}

/** Comment on a post. */
export async function commentOnSkoolPost(postId: string, body: string) {
  return skool(`/groups/${GROUP_SLUG}/posts/${postId}/comments`, {
    method: "POST",
    body: { body },
  });
}

/** Like a post. */
export async function likePost(postId: string) {
  return skool(`/groups/${GROUP_SLUG}/posts/${postId}/likes`, { method: "POST" });
}

/** List community members (30 per page, real data from __NEXT_DATA__). */
export async function listMembers(page = 1) {
  const qs = page > 1 ? `?p=${page}` : "";
  const data = await nextData(`/${GROUP_SLUG}/-/members${qs}`);
  return {
    total: data.total,
    totalPages: data.totalPages,
    page: data.page,
    itemsPerPage: data.itemsPerPage,
    members: (data.users || []).map((u: any) => ({
      id: u.id,
      name: u.name || `${u.firstName || ""} ${u.lastName || ""}`.trim(),
      firstName: u.firstName,
      lastName: u.lastName,
      email: u.email,
      created_at: u.createdAt,
      metadata: u.metadata,
    })),
  };
}

/** LEGACY — api2 members route 404s. */
export async function listMembersLegacy(page = 1, limit = 20) {
  return skool(`/groups/${GROUP_SLUG}/members?page=${page}&limit=${limit}`);
}

/** Get member profile by ID. */
export async function getMember(memberId: string) {
  return skool(`/groups/${GROUP_SLUG}/members/${memberId}`);
}

/** List classroom courses/modules. Returns the full course objects. */
export async function listModules() {
  const data = await nextData(`/${GROUP_SLUG}/classroom`);
  const courses = data.allCourses || [];
  return courses.map((c: any) => ({
    id: c.id,
    name: c.name,
    title: c.metadata?.title,
    description: c.metadata?.desc,
    cover_image: c.metadata?.coverImage,
    unit_type: c.unitType,
    state: c.state,
    public: c.public,
    created_at: c.createdAt,
  }));
}

/** LEGACY — api2 modules route 404s. */
export async function listModulesLegacy() {
  return skool(`/groups/${GROUP_SLUG}/modules`);
}

/** Get a classroom module with lessons. */
export async function getSkoolModule(moduleId: string) {
  return skool(`/groups/${GROUP_SLUG}/modules/${moduleId}`);
}

/** List notifications (DM-like activity). */
export async function listNotifications(page = 1) {
  return skool(`/notifications?page=${page}`);
}

/** Search posts by keyword. */
export async function searchPosts(query: string, page = 1) {
  return skool(`/groups/${GROUP_SLUG}/posts?q=${encodeURIComponent(query)}&page=${page}`);
}

// --- CLI ---

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

    switch (cmd) {
      case "links": {
        const data = await listLinks();
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "add-link": {
        const [title, url] = args;
        if (!title || !url) { console.error("Usage: api.ts add-link <title> <url>"); process.exit(1); }
        await addLink(title, url);
        console.log("added");
        break;
      }
      case "update-link": {
        const [ordinal, title, url] = args;
        if (!ordinal || !title || !url) { console.error("Usage: api.ts update-link <ordinal> <title> <url>"); process.exit(1); }
        await updateLink(Number(ordinal), title, url);
        console.log("updated");
        break;
      }
      case "delete-link": {
        const [ordinal] = args;
        if (!ordinal) { console.error("Usage: api.ts delete-link <ordinal>"); process.exit(1); }
        await deleteLink(Number(ordinal));
        console.log("deleted");
        break;
      }
      case "hide-tab": {
        const [tab] = args;
        if (!tab || !["classroom", "calendar", "map"].includes(tab)) {
          console.error("Usage: api.ts hide-tab <classroom|calendar|map>"); process.exit(1);
        }
        await hideTab(tab as "classroom" | "calendar" | "map");
        console.log(`${tab} hidden`);
        break;
      }
      case "show-tab": {
        const [tab] = args;
        if (!tab || !["classroom", "calendar", "map"].includes(tab)) {
          console.error("Usage: api.ts show-tab <classroom|calendar|map>"); process.exit(1);
        }
        await showTab(tab as "classroom" | "calendar" | "map");
        console.log(`${tab} shown`);
        break;
      }
      case "update-about": {
        const text = args.join(" ");
        if (!text) { console.error("Usage: api.ts update-about <text>"); process.exit(1); }
        await updateAbout(text);
        console.log("about updated");
        break;
      }
      case "update-short-desc": {
        const text = args.join(" ");
        if (!text) { console.error("Usage: api.ts update-short-desc <text>"); process.exit(1); }
        await updateShortDescription(text);
        console.log("short description updated");
        break;
      }
      case "posts": {
        const page = args[0] ? parseInt(args[0], 10) : 1;
        const data = await listSkoolPosts(page);
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "post": {
        const [postId] = args;
        if (!postId) { console.error("Usage: api.ts post <post_id>"); process.exit(1); }
        const data = await getPost(postId);
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "create-post": {
        const [title, ...bodyParts] = args;
        if (!title || !bodyParts.length) { console.error("Usage: api.ts create-post <title> <body>"); process.exit(1); }
        const data = await createSkoolPost(title, bodyParts.join(" "));
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "comment": {
        const [postId, ...bodyParts] = args;
        if (!postId || !bodyParts.length) { console.error("Usage: api.ts comment <post_id> <body>"); process.exit(1); }
        await commentOnSkoolPost(postId, bodyParts.join(" "));
        console.log("commented");
        break;
      }
      case "members": {
        const page = args[0] ? parseInt(args[0], 10) : 1;
        const data = await listMembers(page);
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "modules": {
        const data = await listModules();
        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 searchPosts(query);
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "notifications": {
        const data = await listNotifications();
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [links|add-link|update-link|delete-link|hide-tab|show-tab|update-about|update-short-desc|posts|post|create-post|comment|members|modules|search|notifications] ...");
    }
  })();
}

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