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

{
  "kind": "question_card",
  "post_id": "<skool post id>",
  "post_slug": "<skool post name>",
  "title": "<post title>",
  "author": "<author name>",
  "comment_count": <number>,
  "preview": "<first 120 chars of content>",
  "permalink": "https://www.skool.com/snappy/<slug>",
  "actions": [
    { "label": "View Post", "handler": "skool/post", "args": { "slug": "<slug>" } },
    { "label": "DM Author", "handler": "skool/dm", "args": { "user_id": "<author_id>" } }
  ]
}

- name: fetch_success
  kind: deterministic
  check: Posts fetched without error from community.ts

- name: recency_filter
  kind: deterministic
  check: Only posts from last 30 minutes are included

- name: question_classifier
  kind: deterministic
  check: Question heuristic correctly identifies posts with ? or question-word starters

- name: threshold_applied
  kind: deterministic
  check: Only posts with >=2 comments OR question classification are included

- name: output_shape
  kind: deterministic
  check: Each output line is valid JSON with required fields (kind, post_id, title, actions)

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

npx tsx state/lib/skool-q-scanner.ts

# Run scanner
npx tsx state/lib/skool-q-scanner.ts

# View output
cat /tmp/skool-q-scanner-output.ndjson | jq .

# Check recent evals
tail -5 state/log/evals.ndjson | jq 'select(.skill=="skool-q-scanner")'

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

api.ts- the code it can call

#!/usr/bin/env node
/**
 * snappy-skool-q-scanner/api.ts
 * 
 * Scans Skool community posts from the last 30 minutes and surfaces questions or active threads.
 * Outputs question_card JSON for qualifying posts.
 */

import { listSkoolPosts } from './community.ts';
import { score } from './eval.ts';
import { writeFileSync } from 'fs';

interface SkoolPost {
  id: string;
  slug: string;
  title: string;
  content: string;
  author: {
    id: string;
    name: string;
  };
  comment_count: number;
  created_at: string;
}

interface QuestionCard {
  kind: 'question_card';
  post_id: string;
  post_slug: string;
  title: string;
  author: string;
  comment_count: number;
  preview: string;
  permalink: string;
  actions: Array<{
    label: string;
    handler: string;
    args: Record<string, string>;
  }>;
}

const QUESTION_WORDS = ['how', 'what', 'where', 'when', 'why', 'can', 'could', 'should', 'do', 'does', 'is', 'are'];

/**
 * Check if text contains question indicators
 */
function isQuestion(text: string): boolean {
  if (!text) return false;
  
  // Check for question mark
  if (text.includes('?')) return true;
  
  // Check for question word starters
  const lower = text.toLowerCase().trim();
  return QUESTION_WORDS.some(word => lower.startsWith(word + ' '));
}

/**
 * Check if post was created in the last N minutes
 */
function isRecent(createdAt: string, minutesAgo: number): boolean {
  const postTime = new Date(createdAt).getTime();
  const cutoff = Date.now() - (minutesAgo * 60 * 1000);
  return postTime >= cutoff;
}

/**
 * Format post as question_card
 */
function formatQuestionCard(post: SkoolPost): QuestionCard {
  const preview = post.content.slice(0, 120).trim();
  
  return {
    kind: 'question_card',
    post_id: post.id,
    post_slug: post.slug,
    title: post.title,
    author: post.author.name,
    comment_count: post.comment_count,
    preview,
    permalink: `https://www.skool.com/snappy/${post.slug}`,
    actions: [
      {
        label: 'View Post',
        handler: 'skool/post',
        args: { slug: post.slug }
      },
      {
        label: 'DM Author',
        handler: 'skool/dm',
        args: { user_id: post.author.id }
      }
    ]
  };
}

/**
 * Main scanner function
 */
export async function scanRecentQuestions(
  minutesAgo: number = 30,
  commentThreshold: number = 2
): Promise<QuestionCard[]> {
  const runId = `skool-q-scanner-${Date.now()}`;
  
  try {
    // Fetch posts
    const response = await listSkoolPosts(1, 50); // Fetch more to ensure we catch recent ones
    const allPosts = response.posts || [];
    
    // Filter by recency
    const recentPosts = allPosts.filter((p: SkoolPost) => isRecent(p.created_at, minutesAgo));
    
    // Filter by criteria: question OR active (>=2 comments)
    const qualifying = recentPosts.filter((p: SkoolPost) => {
      const hasQuestion = isQuestion(p.title) || isQuestion(p.content);
      const isActive = p.comment_count >= commentThreshold;
      return hasQuestion || isActive;
    });
    
    // Format as question cards
    const cards = qualifying.map(formatQuestionCard);
    
    // Write output
    const outputPath = '/tmp/skool-q-scanner-output.ndjson';
    const lines = cards.map(c => JSON.stringify(c)).join('\n');
    writeFileSync(outputPath, lines + '\n');
    
    // Log summary
    console.log(`Found ${cards.length} questions/active threads in the last ${minutesAgo} minutes.`);
    console.log(`Output: ${outputPath}`);
    
    // Score eval
    score('skool-q-scanner', runId, {
      
      
      score: 1,
      criteria: {
        fetch_success: { score: 1, rationale: `Fetched ${allPosts.length} posts successfully` },
        recency_filter: { score: 1, rationale: `Filtered to ${recentPosts.length} posts from last ${minutesAgo}min` },
        question_classifier: { score: 1, rationale: `Applied question heuristic (? or question words)` },
        threshold_applied: { score: 1, rationale: `Applied threshold: question OR comment_count >= ${commentThreshold}` },
        output_shape: { score: 1, rationale: `Wrote ${cards.length} valid question_card JSON lines` }
      },
      note: `Scanned ${recentPosts.length} recent posts, surfaced ${cards.length} qualifying items`
    });
    
    return cards;
    
  } catch (error: any) {
    // Log failure
    score('skool-q-scanner', runId, {
      
      
      score: 0,
      criteria: {
        fetch_success: { score: 0, rationale: `Failed: ${error.message}` },
        recency_filter: { score: 0, rationale: 'Not reached' },
        question_classifier: { score: 0, rationale: 'Not reached' },
        threshold_applied: { score: 0, rationale: 'Not reached' },
        output_shape: { score: 0, rationale: 'Not reached' }
      },
      note: `Error during scan: ${error.message}`
    });
    
    throw error;
  }
}

// CLI entrypoint
if (import.meta.url === `file://${process.argv[1]}`) {
  scanRecentQuestions()
    .then(() => process.exit(0))
    .catch((err) => {
      console.error('Scan failed:', err);
      process.exit(1);
    });
}

scripts- helper scripts it can run

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

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