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

criteria:
  - name: blog_ts_exists
    kind: deterministic
    check: "File 'state/lib/blog.ts' must exist."
  - name: list_blog_posts_output_valid
    kind: judge
    check: "The output of listBlogPosts() accurately represents the blog posts available and their frontmatter data based on 'listBlogPosts_input'."
  - name: frontmatter_validation_correct
    kind: judge
    check: "The validateFrontmatter() function correctly identifies valid and invalid frontmatter based on 'validateFrontmatter_input' and relevant schema definitions for blog posts."
  - name: log_entry_created
    kind: deterministic
    check: "An entry for this skill's execution must be present in 'state/log/pending-eval.ndjson'."

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

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-blog/api.ts -- Blog MDX operations for all snappy-* skills.
 *
 * Usage:
 *   npx tsx api.ts list                    # list blog posts in the snappy.ai repo
 *   npx tsx api.ts validate <path>         # validate MDX frontmatter
 *
 * Or import as module:
 *   import { listBlogPosts, validateFrontmatter } from "./blog.ts";
 *
 * Configuration:
 *   SNAPPY_BLOG_DIR  - path to the blog content directory (MDX files).
 *                      Defaults to ~/.snappy-os/blog when unset.
 */

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

const BLOG_DIR = process.env.SNAPPY_BLOG_DIR ?? join(os.homedir(), ".snappy-os", "blog");

const REQUIRED_FIELDS = ["title", "description", "date", "author", "authorRole", "category", "featured", "tags"];
const VALID_CATEGORIES = ["Strategy", "Engineering", "AI", "Business", "Case Study"];

interface PostInfo {
  slug: string;
  path: string;
  title: string;
  date: string;
  category: string;
  featured: boolean;
}

interface ValidationResult {
  valid: boolean;
  errors: string[];
  warnings: string[];
}

/** Lists blog posts from the snappy.ai repo. */
export function listBlogPosts(): PostInfo[] {
  if (!existsSync(BLOG_DIR)) return [];
  const files = readdirSync(BLOG_DIR).filter((f) => f.endsWith(".mdx")).sort();
  const posts: PostInfo[] = [];

  for (const file of files) {
    const content = readFileSync(join(BLOG_DIR, file), "utf-8");
    const fm = parseFrontmatter(content);
    posts.push({
      slug: file.replace(".mdx", ""),
      path: join(BLOG_DIR, file),
      title: fm.title || "(untitled)",
      date: fm.date || "(no date)",
      category: fm.category || "(none)",
      featured: fm.featured === true || fm.featured === "true",
    });
  }
  return posts;
}

/** Validates MDX frontmatter against snappy-publish schema. */
export function validateFrontmatter(mdxContent: string): ValidationResult {
  const errors: string[] = [];
  const warnings: string[] = [];
  const fm = parseFrontmatter(mdxContent);

  if (!fm._found) {
    errors.push("No YAML frontmatter found (must start with ---)");
    return { valid: false, errors, warnings };
  }

  for (const field of REQUIRED_FIELDS) {
    if (fm[field] === undefined || fm[field] === null || fm[field] === "") {
      errors.push(`Missing required field: ${field}`);
    }
  }

  if (fm.category && !VALID_CATEGORIES.includes(fm.category)) {
    errors.push(`Invalid category "${fm.category}". Must be one of: ${VALID_CATEGORIES.join(", ")}`);
  }

  if (fm.tags && !Array.isArray(fm.tags)) {
    errors.push("tags must be a YAML array, not a comma string");
  }

  if (fm.description && String(fm.description).length > 160) {
    warnings.push(`description is ${String(fm.description).length} chars (should be < 160)`);
  }

  // Word count check
  const body = mdxContent.split("---").slice(2).join("---").trim();
  const wordCount = body.split(/\s+/).filter(Boolean).length;
  if (wordCount < 800) warnings.push(`Body is ${wordCount} words (minimum 800)`);
  if (wordCount > 1200) warnings.push(`Body is ${wordCount} words (maximum 1200)`);

  return { valid: errors.length === 0, errors, warnings };
}

/** Simple YAML frontmatter parser (no dependencies). */
function parseFrontmatter(content: string): Record<string, any> {
  const match = content.match(/^---\n([\s\S]*?)\n---/);
  if (!match) return { _found: false };

  const result: Record<string, any> = { _found: true };
  const lines = match[1].split("\n");
  let currentKey = "";
  let inArray = false;
  let arrayValues: string[] = [];

  for (const line of lines) {
    if (inArray) {
      if (line.match(/^\s+-\s+/)) {
        arrayValues.push(line.replace(/^\s+-\s+/, "").trim());
        continue;
      } else {
        result[currentKey] = arrayValues;
        inArray = false;
        arrayValues = [];
      }
    }

    const kvMatch = line.match(/^(\w+):\s*(.*)/);
    if (kvMatch) {
      const [, key, val] = kvMatch;
      currentKey = key;
      if (val.trim() === "") {
        inArray = true;
        arrayValues = [];
      } else {
        let parsed: any = val.trim().replace(/^["']|["']$/g, "");
        if (parsed === "true") parsed = true;
        if (parsed === "false") parsed = false;
        result[key] = parsed;
      }
    }
  }

  if (inArray) result[currentKey] = arrayValues;
  return result;
}

// --- CLI ---

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

    switch (cmd) {
      case "list": {
        const posts = listBlogPosts();
        console.log(`${posts.length} blog posts:`);
        for (const p of posts) {
          console.log(`  ${p.date}\t${p.slug}\t${p.category}\t${p.featured ? "FEATURED" : ""}`);
        }
        break;
      }
      case "validate": {
        const [path] = args;
        if (!path) { console.error("Usage: api.ts validate <path>"); process.exit(1); }
        const absPath = path.startsWith("/") ? path : join(BLOG_DIR, path);
        const content = readFileSync(absPath, "utf-8");
        const result = validateFrontmatter(content);
        console.log(`Valid: ${result.valid}`);
        for (const e of result.errors) console.log(`  ERROR: ${e}`);
        for (const w of result.warnings) console.log(`  WARN: ${w}`);
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [list|validate] ...");
    }
  })();
}

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