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

import {
  getRecentTelegramMessages,
  sendText,
  sendPhoto,
  sendDocument,
} from "./state/lib/telegram.ts";

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

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

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-telegram/api.ts -- Telegram Bot API operations for all snappy-* skills.
 *
 * Uses Telegram Bot Token from snappy-settings/.env.cache.
 * Direct Telegram Bot API calls.
 *
 * Usage:
 *   npx tsx api.ts send "Hello from the agent"
 *   npx tsx api.ts send "Hello" --parse-mode HTML
 *   npx tsx api.ts photo "https://example.com/img.jpg"
 *
 * Or import as module:
 *   import { sendText, sendPhoto, editTelegramMessage, deleteTelegramMessage, getRecentTelegramMessages } from "./telegram.ts";
 */

import { env } from "./env.ts";
import { realpathSync } from "fs";

const BASE = () => `https://api.telegram.org/bot${env("TELEGRAM_BOT_TOKEN")}`;
const ROBERT_CHAT_ID = () => env("TELEGRAM_ROBERT_CHAT_ID");

async function tg(method: string, body: Record<string, unknown>) {
  const res = await fetch(`${BASE()}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  const data = await res.json();
  if (!data.ok) {
    throw new Error(`Telegram ${method} failed: ${data.description}`);
  }
  return data.result;
}

// --- Public API ---

export async function sendText(
  text: string,
  parseMode: "Markdown" | "HTML" = "Markdown",
  chatId?: string,
) {
  return tg("sendMessage", {
    chat_id: chatId || ROBERT_CHAT_ID(),
    text,
    parse_mode: parseMode,
  });
}

export async function sendPhoto(photoUrl: string, caption?: string, chatId?: string) {
  return tg("sendPhoto", {
    chat_id: chatId || ROBERT_CHAT_ID(),
    photo: photoUrl,
    ...(caption ? { caption, parse_mode: "Markdown" } : {}),
  });
}

export async function sendDocument(documentUrl: string, caption?: string, chatId?: string) {
  return tg("sendDocument", {
    chat_id: chatId || ROBERT_CHAT_ID(),
    document: documentUrl,
    ...(caption ? { caption } : {}),
  });
}

export async function editTelegramMessage(
  messageId: number,
  text: string,
  parseMode: "Markdown" | "HTML" = "Markdown",
  chatId?: string,
) {
  return tg("editMessageText", {
    chat_id: chatId || ROBERT_CHAT_ID(),
    message_id: messageId,
    text,
    parse_mode: parseMode,
  });
}

export async function sendChatAction(
  action: "typing" | "upload_photo" | "upload_document" = "typing",
  chatId?: string,
) {
  return tg("sendChatAction", {
    chat_id: chatId || ROBERT_CHAT_ID(),
    action,
  });
}

// --- Read operations ---

export async function getUpdates(offset?: number, limit = 100, timeout = 0) {
  return tg("getUpdates", {
    ...(offset !== undefined ? { offset } : {}),
    limit,
    timeout,
    allowed_updates: ["message", "edited_message", "channel_post"],
  });
}

export async function getRecentTelegramMessages(
  chatId?: string,
  limit = 20,
): Promise<
  Array<{
    message_id: number;
    from: string;
    text: string;
    date: string;
    chat_id: number;
  }>
> {
  const updates = await getUpdates(undefined, 100, 0);
  const targetChat = chatId || ROBERT_CHAT_ID();
  const messages = (updates as any[])
    .filter((u: any) => u.message && String(u.message.chat.id) === String(targetChat))
    .map((u: any) => ({
      message_id: u.message.message_id,
      from: u.message.from?.first_name || u.message.from?.username || "unknown",
      text: u.message.text || u.message.caption || "[non-text]",
      date: new Date(u.message.date * 1000).toISOString(),
      chat_id: u.message.chat.id,
    }))
    .slice(-limit);
  return messages;
}

export async function deleteTelegramMessage(messageId: number, chatId?: string) {
  return tg("deleteMessage", {
    chat_id: chatId || ROBERT_CHAT_ID(),
    message_id: messageId,
  });
}

export async function forwardMessage(messageId: number, toChatId: string, fromChatId?: string) {
  return tg("forwardMessage", {
    chat_id: toChatId,
    from_chat_id: fromChatId || ROBERT_CHAT_ID(),
    message_id: messageId,
  });
}

export async function getMe() {
  return tg("getMe", {});
}

// --- CLI ---

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

    switch (cmd) {
      case "send": {
        const parseMode = args.includes("--parse-mode")
          ? (args[args.indexOf("--parse-mode") + 1] as "Markdown" | "HTML")
          : "Markdown";
        const text = args
          .filter((a, i) => a !== "--parse-mode" && args[i - 1] !== "--parse-mode")
          .join(" ");
        if (!text) {
          console.error("Usage: api.ts send <text> [--parse-mode HTML]");
          process.exit(1);
        }
        const result = await sendText(text, parseMode);
        console.log(`sent message_id=${result.message_id}`);
        break;
      }
      case "photo": {
        const [url, ...captionParts] = args;
        if (!url) {
          console.error("Usage: api.ts photo <url> [caption]");
          process.exit(1);
        }
        const result = await sendPhoto(url, captionParts.join(" ") || undefined);
        console.log(`sent photo message_id=${result.message_id}`);
        break;
      }
      case "edit": {
        const [msgId, ...textParts] = args;
        if (!msgId || !textParts.length) {
          console.error("Usage: api.ts edit <message_id> <text>");
          process.exit(1);
        }
        await editTelegramMessage(Number(msgId), textParts.join(" "));
        console.log("edited");
        break;
      }
      case "read": {
        const limit = args[0] ? parseInt(args[0], 10) : 20;
        const msgs = await getRecentTelegramMessages(undefined, limit);
        if (msgs.length === 0) {
          console.log(
            "No recent messages (bot must have received messages via /start or direct chat)",
          );
        } else {
          for (const m of msgs) {
            console.log(`${m.date}\t${m.from}\t${m.text.slice(0, 300)}`);
          }
        }
        break;
      }
      case "updates": {
        const updates = await getUpdates();
        console.log(JSON.stringify(updates, null, 2));
        break;
      }
      case "me": {
        const me = await getMe();
        console.log(JSON.stringify(me, null, 2));
        break;
      }
      case "delete": {
        const [msgId] = args;
        if (!msgId) {
          console.error("Usage: api.ts delete <message_id>");
          process.exit(1);
        }
        await deleteTelegramMessage(Number(msgId));
        console.log("deleted");
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [send|photo|edit|read|updates|me|delete] ...");
    }
  })();
}

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