platform/src/servers/skills/load.ts

import { readdirSync, readFileSync, existsSync } from 'node:fs';
import { join } from 'node:path';
import { OFFICER_ITEMS_DIR } from '../data-path';

// Skills: reference the agent reads WHEN IT NEEDS IT, not on every turn.
//
// ── The inverse of an affordance, on purpose ──
//
//   affordance   body always compiled in, `description` never sent
//   skill        `description` always compiled in, body read on demand
//
// An affordance is a fact about the surface, it is short, and every conversation needs it. A skill is
// reference material — a database schema, a tool's conventions — that is dead weight in a conversation
// about something else. So what gets compiled into the prompt is the INDEX: name, one line of when to
// reach for it, and the path. The body costs nothing until the agent decides it is worth opening.
//
// ── Why a path and not a protocol ──
//
// Progressive disclosure is normally a harness feature: Claude Code discovers `.claude/skills/`, opencode
// has its own conventions, the next one will have a third. Pointing at a file needs none of that — every
// harness worth running can already read a file, and the index is just text in the prompt.
//
// The cost is that the agent has to CHOOSE to read it, where a tool definition would be pushed into its
// face. That is what the description is for, and it is why a vague one makes a skill useless rather than
// merely verbose.

const YAML = (Bun as unknown as { YAML: { parse(input: string): unknown } }).YAML;

export const SKILLS_DIR = join(OFFICER_ITEMS_DIR, 'skills');

export type Skill = {
  /** Directory name — `email-db`. Unique within the store. */
  id: string;
  name: string;
  /** WHEN to reach for this. The only thing the agent sees before deciding to open the body. */
  description: string;
  /** Absolute path to SKILL.md. The agent cannot guess it, so the platform supplies it. */
  path: string;
};

function frontmatter(raw: string): Record<string, unknown> {
  const match = raw.match(/^---\n([\s\S]*?)\n---/);
  if (!match) return {};
  try {
    return (YAML.parse(match[1]!) as Record<string, unknown>) ?? {};
  } catch {
    return {};
  }
}

/**
 * Every skill in the store, sorted so the compiled block is stable.
 *
 * A skill with no `description` is SKIPPED rather than listed with a placeholder. The description is the
 * entire mechanism — a line that does not say when to reach for something is worse than an absent entry,
 * because it costs context in every conversation and earns nothing.
 *
 * Synchronous, like `loadAffordances`, and for the same reason: this runs once per session.
 */
export function loadSkills(root: string = SKILLS_DIR): Skill[] {
  let entries: string[];
  try {
    entries = readdirSync(root, { withFileTypes: true })
      .filter((e) => e.isDirectory())
      .map((e) => e.name);
  } catch {
    return []; // no directory yet is the ordinary state of a fresh install
  }

  const found = entries.sort().map((dir): Skill | null => {
    const path = join(root, dir, 'SKILL.md');
    if (!existsSync(path)) return null;
    try {
      const fm = frontmatter(readFileSync(path, 'utf8'));
      const description = fm.description == null ? '' : String(fm.description).trim();
      if (!description) return null;
      return { id: dir, name: fm.name == null ? dir : String(fm.name), description, path };
    } catch {
      return null;
    }
  });

  return found.filter((s): s is Skill => s !== null);
}

/**
 * The index, for the system prompt. Null when there is nothing to offer.
 *
 * Says READ THIS FILE explicitly. An agent that is merely told a skill exists tends to answer from
 * memory about a schema it has never seen, which is worse than not knowing — the whole point is to stop
 * it guessing at a database it could simply look at.
 */
export function compileSkills(skills: Skill[]): string | null {
  if (!skills.length) return null;
  return [
    '# Skills on this machine',
    '',
    'Reference written for this machine, kept out of your context until you need it. When one of these',
    'covers what you are about to do, READ THE FILE first — it will be more current than anything you',
    'remember, and it exists so you do not have to rediscover what is already written down.',
    '',
    ...skills.map((s) => `- **${s.name}** — ${s.description}\n  Read: \`${s.path}\``),
  ].join('\n');
}

/** Read and compile in one step, for callers that only want the string. */
export function skillsBlock(root: string = SKILLS_DIR): string | null {
  return compileSkills(loadSkills(root));
}