pi-roundtable 0.1.0

package/src/core/modules/schedules/schedule.test.ts

@@ -0,0 +1,358 @@
+import {
+	afterAll,
+	beforeAll,
+	beforeEach,
+	describe,
+	expect,
+	test,
+} from "bun:test";
+import { SQL } from "bun";
+import { ScheduleError } from "../../domain/errors.ts";
+import { messages } from "../../i18n/index.ts";
+import { silentLogger } from "../../log.ts";
+import {
+	describeDb,
+	openTestStore,
+	type TestStore,
+	testDatabaseUrl,
+} from "../../testing/database.ts";
+import { useTestLocale } from "../../testing/locale.ts";
+import { setTimeZone, zonedStamp } from "../../time.ts";
+import { describeRecurrence, nextRun, parseRecurrence } from "./recurrence.ts";
+import { type Schedule, ScheduleStore } from "./schedule-store.ts";
+import {
+	callScheduleTool,
+	SCHEDULE_LIMITS,
+	type ScheduleToolContext,
+	scheduledTurnText,
+} from "./schedule-tools.ts";
+import { type ScheduledOutcome, Scheduler } from "./scheduler.ts";
+
+const taipei = (stamp: string) =>
+	new Date(`${stamp.replace(" ", "T")}:00+08:00`);
+
+// The schedules below are written in Taipei time; the suite's other files keep the neutral zone.
+beforeAll(() => setTimeZone("Asia/Taipei"));
+afterAll(useTestLocale);
+
+describe("recurrence", () => {
+	const now = taipei("2026-09-26 23:30");
+
+	test("a one-time run is the given Taipei time, and none once it has passed", () => {
+		const once = parseRecurrence({ at: "2026-09-27 09:00" }, now);
+		expect(nextRun(once, now)).toEqual(taipei("2026-09-27 09:00"));
+		expect(nextRun(once, taipei("2026-09-27 09:00"))).toBeUndefined();
+	});
+
+	test("in_minutes is one run that many minutes ahead, rounded up to the minute", () => {
+		const at = new Date(taipei("2026-09-26 23:58").getTime() + 30_000);
+		const relative = parseRecurrence({ in_minutes: 2 }, at);
+		expect(relative).toEqual({
+			kind: "once",
+			date: "2026-09-27",
+			time: "00:01",
+		});
+		expect(() =>
+			parseRecurrence({ in_minutes: 2, at: "2026-09-27 09:00" }, at),
+		).toThrow(ScheduleError);
+		expect(() => parseRecurrence({ in_minutes: 0 }, at)).toThrow(ScheduleError);
+	});
+
+	test("every n days counts from the start date and never returns the current instant", () => {
+		const every = parseRecurrence(
+			{ time: "09:00", every_days: 3, start_date: "2026-09-16" },
+			now,
+		);
+		expect(nextRun(every, now)).toEqual(taipei("2026-09-28 09:00"));
+		expect(nextRun(every, taipei("2026-09-28 09:00"))).toEqual(
+			taipei("2026-10-01 09:00"),
+		);
+		expect(describeRecurrence(every)).toBe(
+			messages().scheduleEveryDays(3, "09:00", "2026-09-16"),
+		);
+	});
+
+	test("daily defaults to starting today, so a time still ahead runs today", () => {
+		const daily = parseRecurrence({ time: "23:45" }, now);
+		expect(nextRun(daily, now)).toEqual(taipei("2026-09-26 23:45"));
+		expect(describeRecurrence(daily)).toBe(messages().scheduleDaily("23:45"));
+	});
+
+	test("weekly runs on the listed weekdays", () => {
+		// 2026-09-26 is a Saturday.
+		const weekly = parseRecurrence(
+			{ time: "08:00", weekdays: ["wed", "mon"] },
+			now,
+		);
+		expect(nextRun(weekly, now)).toEqual(taipei("2026-09-28 08:00"));
+		expect(nextRun(weekly, taipei("2026-09-28 08:00"))).toEqual(
+			taipei("2026-09-30 08:00"),
+		);
+		expect(describeRecurrence(weekly)).toBe(
+			messages().scheduleWeekly(
+				[messages().scheduleWeekday("mon"), messages().scheduleWeekday("wed")],
+				"08:00",
+			),
+		);
+	});
+
+	test("bad timing is refused with a message the model can act on", () => {
+		const cases = [
+			{},
+			{ at: "2026-02-30 09:00" },
+			{ at: "tomorrow" },
+			{ at: "2026-09-27 09:00", time: "09:00" },
+			{ time: "25:00" },
+			{ time: "09:00", every_days: 0 },
+			{ time: "09:00", weekdays: ["someday"] },
+			{ time: "09:00", weekdays: ["mon"], every_days: 2 },
+		];
+		for (const input of cases)
+			expect(() => parseRecurrence(input, now)).toThrow(ScheduleError);
+	});
+});
+
+// Runs against a real PostgreSQL, only when ROUNDTABLE_TEST_DATABASE_URL is set.
+describeDb("PostgreSQL", () => {
+	let store: TestStore<ScheduleStore>;
+
+	beforeAll(async () => {
+		const admin = new SQL(testDatabaseUrl);
+		await admin`DROP TABLE IF EXISTS schedules`;
+		await admin.close();
+		store = await openTestStore(ScheduleStore);
+	});
+
+	afterAll(async () => {
+		await store.close();
+	});
+
+	beforeEach(async () => {
+		const admin = new SQL(testDatabaseUrl);
+		await admin`TRUNCATE schedules`;
+		await admin.close();
+	});
+
+	const now = taipei("2026-09-26 23:30");
+	const ctx = (
+		over: Partial<ScheduleToolContext> = {},
+	): ScheduleToolContext => ({
+		store,
+		channel: "discord:a",
+		mode: "party",
+		author: { id: "u1", name: "Sam" },
+		now,
+		...over,
+	});
+
+	describe("schedule tools", () => {
+		test("a schedule keeps its creator's tier, and a lower tier cannot change it", async () => {
+			const admin = { id: "u2", name: "Ada", tier: "admin" } as const;
+			const member = { id: "u3", name: "Max", tier: "member" } as const;
+			await callScheduleTool(ctx({ author: admin }), "schedule_create", {
+				title: "patrol",
+				prompt: "check the disk",
+				time: "09:00",
+				every_days: 1,
+			});
+			const [schedule] = await store.forChannel("discord:a");
+			const id = schedule?.id ?? 0;
+			expect(schedule?.createdTier).toBe("admin");
+			for (const tool of ["schedule_update", "schedule_cancel"] as const)
+				await expect(
+					callScheduleTool(ctx({ author: member }), tool, {
+						id,
+						title: "renamed",
+					}),
+				).rejects.toThrow(/higher tier/);
+			await callScheduleTool(ctx({ author: admin }), "schedule_update", {
+				id,
+				title: "renamed",
+			});
+			expect((await store.get(id))?.title).toBe("renamed");
+			// The owner's own schedules default to the owner's tier.
+			await callScheduleTool(ctx(), "schedule_create", {
+				title: "morning report",
+				prompt: "report",
+				time: "10:00",
+				every_days: 1,
+			});
+			const owners = await store.forChannel("discord:a");
+			expect(owners.map((x) => x.createdTier).sort()).toEqual([
+				"admin",
+				"owner",
+			]);
+		});
+
+		test("create, list, update, and cancel act on the channel's schedules", async () => {
+			const created = await callScheduleTool(ctx(), "schedule_create", {
+				title: "jobs",
+				prompt: "find pastry shop openings",
+				time: "09:00",
+				every_days: 3,
+				start_date: "2026-09-16",
+			});
+			expect(created).toContain("first run 2026-09-28 09:00");
+			const [schedule] = await store.forChannel("discord:a");
+			expect(schedule?.createdByName).toBe("Sam");
+			expect(schedule?.mode).toBe("party");
+
+			const id = schedule?.id ?? 0;
+			expect(await callScheduleTool(ctx(), "schedule_list", {})).toContain(
+				`#${id} jobs`,
+			);
+			await callScheduleTool(ctx(), "schedule_update", {
+				id,
+				prompt: "find pastry shop openings; already seen: Acme",
+			});
+			expect(await callScheduleTool(ctx(), "schedule_list", { id })).toContain(
+				"already seen: Acme",
+			);
+			// Changing only the prompt keeps the timing.
+			expect((await store.get(id))?.nextRun).toEqual(
+				taipei("2026-09-28 09:00"),
+			);
+
+			await callScheduleTool(ctx(), "schedule_update", { id, time: "20:00" });
+			expect((await store.get(id))?.nextRun).toEqual(
+				taipei("2026-09-27 20:00"),
+			);
+
+			expect(
+				callScheduleTool(ctx({ channel: "discord:b" }), "schedule_cancel", {
+					id,
+				}),
+			).rejects.toThrow(ScheduleError);
+			await callScheduleTool(ctx(), "schedule_cancel", { id });
+			expect(await store.forChannel("discord:a")).toEqual([]);
+		});
+
+		test("a party channel is limited in count, prompt size, and distance", async () => {
+			const { perChannel, promptChars } = SCHEDULE_LIMITS.party;
+			for (let i = 0; i < perChannel; i += 1)
+				await callScheduleTool(ctx(), "schedule_create", {
+					title: `t${i}`,
+					prompt: "p",
+					time: "10:00",
+				});
+			expect(
+				callScheduleTool(ctx(), "schedule_create", {
+					title: "one more",
+					prompt: "p",
+					time: "10:00",
+				}),
+			).rejects.toThrow("cancel one first");
+			expect(
+				callScheduleTool(ctx({ channel: "discord:b" }), "schedule_create", {
+					title: "long",
+					prompt: "x".repeat(promptChars + 1),
+					time: "10:00",
+				}),
+			).rejects.toThrow(`within ${promptChars}`);
+			expect(
+				callScheduleTool(ctx({ channel: "discord:b" }), "schedule_create", {
+					title: "far",
+					prompt: "p",
+					at: "2027-09-26 10:00",
+				}),
+			).rejects.toThrow("within 90 days");
+			expect(
+				callScheduleTool(ctx({ channel: "discord:b" }), "schedule_create", {
+					title: "past",
+					prompt: "p",
+					at: "2026-09-26 10:00",
+				}),
+			).rejects.toThrow("already passed");
+		});
+
+		test("the scheduled message names the schedule and carries its prompt", async () => {
+			await callScheduleTool(ctx(), "schedule_create", {
+				title: "drink water",
+				prompt: "remind Sam to drink water",
+				at: "2026-09-27 09:00",
+			});
+			const [schedule] = await store.forChannel("discord:a");
+			if (!schedule) throw new Error("missing schedule");
+			const text = scheduledTurnText(schedule, taipei("2026-09-27 09:00"));
+			expect(text).toContain(`#${schedule.id}: drink water`);
+			expect(text).toContain("2026-09-27 09:00");
+			expect(text.endsWith("remind Sam to drink water")).toBe(true);
+		});
+	});
+
+	describe("scheduler", () => {
+		function scheduler(
+			clock: { now: Date },
+			fired: Schedule[],
+			outcome: ScheduledOutcome,
+		) {
+			return new Scheduler({
+				store,
+				runner: {
+					runScheduled: async (schedule) => {
+						fired.push(schedule);
+						return outcome;
+					},
+				},
+				logger: silentLogger(),
+				now: () => clock.now,
+			});
+		}
+
+		test("a due one-time schedule fires once and is deleted", async () => {
+			await callScheduleTool(ctx(), "schedule_create", {
+				title: "once",
+				prompt: "p",
+				at: "2026-09-27 09:00",
+			});
+			const clock = { now: taipei("2026-09-27 08:59") };
+			const fired: Schedule[] = [];
+			const s = scheduler(clock, fired, { status: "ran" });
+			await s.tick();
+			expect(fired).toHaveLength(0);
+			clock.now = taipei("2026-09-27 09:00");
+			await s.tick();
+			await s.tick();
+			await s.idle();
+			expect(fired.map((f) => f.title)).toEqual(["once"]);
+			expect(await store.forChannel("discord:a")).toEqual([]);
+		});
+
+		test("a repeating schedule moves to its next run and keeps the outcome", async () => {
+			await callScheduleTool(ctx(), "schedule_create", {
+				title: "daily",
+				prompt: "p",
+				time: "09:00",
+			});
+			const clock = { now: taipei("2026-09-27 09:00") };
+			const fired: Schedule[] = [];
+			const s = scheduler(clock, fired, {
+				status: "skipped",
+				reason: "party mode is off",
+			});
+			await s.tick();
+			await s.idle();
+			const [after] = await store.forChannel("discord:a");
+			expect(fired).toHaveLength(1);
+			expect(after && zonedStamp(after.nextRun)).toBe("2026-09-28 09:00");
+			expect(after?.lastStatus).toBe("skipped: party mode is off");
+		});
+
+		test("a run found long after it was due is skipped, not caught up", async () => {
+			await callScheduleTool(ctx(), "schedule_create", {
+				title: "daily",
+				prompt: "p",
+				time: "09:00",
+			});
+			const clock = { now: taipei("2026-09-29 12:00") };
+			const fired: Schedule[] = [];
+			const s = scheduler(clock, fired, { status: "ran" });
+			await s.tick();
+			await s.idle();
+			const [after] = await store.forChannel("discord:a");
+			expect(fired).toHaveLength(0);
+			expect(after && zonedStamp(after.nextRun)).toBe("2026-09-30 09:00");
+			expect(after?.lastStatus).toBe("skipped: missed while offline");
+		});
+	});
+});

package/src/core/modules/schedules/scheduler.ts

@@ -0,0 +1,121 @@
+import type { ScheduledOutcome } from "../../contract/channels.ts";
+import type { Logger } from "../../log.ts";
+import { nextRun } from "./recurrence.ts";
+import type { Schedule, ScheduleStore } from "./schedule-store.ts";
+
+export type { ScheduledOutcome };
+
+export interface ScheduledRunner {
+	/** Runs one due schedule in its channel and posts the answer there; never rejects. */
+	runScheduled(schedule: Schedule, firedAt: Date): Promise<ScheduledOutcome>;
+}
+
+/** A run found this late, for example after the service was down, is skipped instead of run. */
+export const LATE_LIMIT_MS = 12 * 3_600_000;
+
+export interface SchedulerOptions {
+	store: Pick<ScheduleStore, "due" | "claim" | "recordStatus">;
+	runner: ScheduledRunner;
+	logger: Logger;
+	intervalMs?: number;
+	/** Replaceable in tests. */
+	now?: () => Date;
+}
+
+function statusText(outcome: ScheduledOutcome): string {
+	switch (outcome.status) {
+		case "ran":
+			return "ran";
+		case "failed":
+			return `failed: ${outcome.error}`.slice(0, 300);
+		case "skipped":
+			return `skipped: ${outcome.reason}`;
+	}
+}
+
+/**
+ * Checks for due schedules on an interval. Each due schedule is claimed first, moved to its
+ * next run or deleted, so a slow or failing run never fires twice; missed runs are not caught up.
+ */
+export class Scheduler {
+	readonly #options: SchedulerOptions;
+	readonly #running = new Set<Promise<void>>();
+	#timer: ReturnType<typeof setInterval> | undefined;
+	#ticking = false;
+
+	constructor(options: SchedulerOptions) {
+		this.#options = options;
+	}
+
+	start(): void {
+		this.#timer = setInterval(
+			() => void this.tick(),
+			this.#options.intervalMs ?? 30_000,
+		);
+		void this.tick();
+	}
+
+	stop(): void {
+		clearInterval(this.#timer);
+	}
+
+	/** Claims every due schedule and starts its run; runs continue after tick resolves. */
+	async tick(): Promise<void> {
+		if (this.#ticking) return;
+		this.#ticking = true;
+		const { store, logger } = this.#options;
+		try {
+			const now = this.#options.now?.() ?? new Date();
+			for (const schedule of await store.due(now)) {
+				const claimed = await store.claim(
+					schedule,
+					nextRun(schedule.recurrence, now),
+					now,
+				);
+				if (!claimed) continue;
+				if (now.getTime() - schedule.nextRun.getTime() > LATE_LIMIT_MS) {
+					logger.warn(
+						{ schedule: schedule.id, due: schedule.nextRun },
+						"schedule missed its run",
+					);
+					await store.recordStatus(
+						schedule.id,
+						"skipped: missed while offline",
+					);
+					continue;
+				}
+				const run = this.#fire(schedule, now).finally(() =>
+					this.#running.delete(run),
+				);
+				this.#running.add(run);
+			}
+		} catch (error) {
+			logger.error({ err: error }, "schedule check failed");
+		} finally {
+			this.#ticking = false;
+		}
+	}
+
+	/** Resolves once every started run has finished. */
+	async idle(): Promise<void> {
+		await Promise.all([...this.#running]);
+	}
+
+	async #fire(schedule: Schedule, firedAt: Date): Promise<void> {
+		const { store, runner, logger } = this.#options;
+		logger.info(
+			{ schedule: schedule.id, channel: schedule.channel, mode: schedule.mode },
+			"schedule firing",
+		);
+		const outcome = await runner.runScheduled(schedule, firedAt);
+		logger.info({ schedule: schedule.id, outcome }, "schedule finished");
+		await store
+			.recordStatus(schedule.id, statusText(outcome))
+			.catch((error: unknown) =>
+				logger.error(
+					{ schedule: schedule.id, err: error },
+					"schedule status not saved",
+				),
+			);
+	}
+}

package/src/core/modules/schedules/schedules.ts

@@ -0,0 +1,87 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { ChannelKey } from "../../domain/conversation.ts";
+import { ScheduleError } from "../../domain/errors.ts";
+import type { OwnerIdentity } from "../../identity.ts";
+import {
+	type ToolInput,
+	textToolsExtension,
+} from "../../runtime/text-tools.ts";
+import {
+	type ScheduleToolSpec,
+	scheduleToolSpecs,
+} from "../../shared/schedule-tools.ts";
+import type { Speaker } from "../../speakers.ts";
+import type { ScheduleStore } from "./schedule-store.ts";
+import { callScheduleTool } from "./schedule-tools.ts";
+
+export interface OwnerSchedules {
+	store: ScheduleStore;
+	owner: { id: string; name: string };
+	/**
+	 * The chat channel a conversation's schedules belong to: itself, or the owner's direct
+	 * messages for a conversation no chat surface carries, where a run could not be posted.
+	 */
+	channelFor: (channel: ChannelKey) => Promise<ChannelKey>;
+}
+
+/** Finds another agent's channel, for reading its schedules; throws ScheduleError when there is none. */
+export type AgentChannelLookup = (agent: string) => ChannelKey;
+
+/** schedule_list for agents: an optional agent name reads that agent's schedules instead. */
+function withAgentOption(spec: ScheduleToolSpec): ScheduleToolSpec {
+	if (spec.name !== "schedule_list") return spec;
+	return {
+		...spec,
+		description: `${spec.description} Give agent to read another agent's schedules instead; you can change only your own, so ask that agent to change its.`,
+		parameters: Type.Object({
+			id: Type.Optional(Type.Integer({ description: "Schedule id." })),
+			agent: Type.Optional(
+				Type.String({ description: "Another agent's name, from agent_list." }),
+			),
+		}),
+	};
+}
+
+/**
+ * Registers the schedule tools for one owner conversation; its runs speak for the owner. With
+ * `agents`, schedule_list can also read another agent's schedules.
+ */
+export function schedulesExtension(
+	schedules: OwnerSchedules,
+	channel: ChannelKey,
+	identity: OwnerIdentity,
+	agents?: AgentChannelLookup,
+	/** The person the running turn is for; their schedules run at their tier. */
+	speaker: () => Speaker | undefined = () => undefined,
+): ExtensionFactory {
+	const { store, owner, channelFor } = schedules;
+	const defs = scheduleToolSpecs().map((base) => {
+		const spec = agents ? withAgentOption(base) : base;
+		return {
+			...spec,
+			run: async (input: ToolInput) => {
+				const peer =
+					agents && typeof input.agent === "string" && input.agent
+						? agents(input.agent)
+						: undefined;
+				const target = peer ?? (await channelFor(channel));
+				const answer = await callScheduleTool(
+					{
+						store,
+						channel: target,
+						mode: "owner",
+						author: speaker() ?? owner,
+						now: new Date(),
+					},
+					spec.name,
+					input,
+				);
+				if (peer) return `Agent ${String(input.agent)}'s channel:\n${answer}`;
+				if (target === channel) return answer;
+				return `${answer}\n(These are the schedules of ${identity.name}'s Discord direct messages; their runs are posted there.)`;
+			},
+		};
+	});
+	return textToolsExtension(defs, ScheduleError);
+}

package/src/core/modules/skills/repo-name.ts

@@ -0,0 +1,11 @@
+import { AgentError } from "../../domain/errors.ts";
+
+export function checkRepoName(repo: string): void {
+	if (
+		!/^[\w.-]+\/[\w.-]+$/.test(repo) ||
+		repo.split("/").some((p) => /^\.+$/.test(p))
+	)
+		throw new AgentError(
+			`"${repo}" is not a repository: write it as <owner>/<repo>, as repo_list shows.`,
+		);
+}

package/src/core/modules/skills/skill-kind.test.ts

@@ -0,0 +1,55 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { SQL } from "bun";
+import { migrate } from "../../db/migrations.ts";
+import {
+	describeDb,
+	migratedPool,
+	TEST_GUILD,
+	testDatabaseUrl,
+} from "../../testing/database.ts";
+import { LEGACY_WRITTEN_KIND, SkillStore } from "./skill-store.ts";
+
+// Runs against a real PostgreSQL, only when ROUNDTABLE_TEST_DATABASE_URL is set.
+describeDb("the written skill kind", () => {
+	let sql: SQL;
+
+	beforeEach(async () => {
+		const admin = new SQL(testDatabaseUrl);
+		for (const table of ["skills", "skill_groups", "agent_skills"])
+			await admin.unsafe(`DROP TABLE IF EXISTS ${table}`);
+		await admin.close();
+		// The tables as they were when an agent-written skill was stored under the legacy kind.
+		sql = await migratedPool(SkillStore.migration);
+		await sql`INSERT INTO skills (name, kind, description, body)
+			VALUES ('notes', ${LEGACY_WRITTEN_KIND}, 'Take notes.', 'Body.')`;
+		await sql`INSERT INTO skills (name, kind, repo, path)
+			VALUES ('linked-one', 'linked', 'owner/repo', 'skills/linked-one')`;
+	});
+
+	afterEach(async () => {
+		await sql.close();
+	});
+
+	const kinds = async () =>
+		(await sql`SELECT name, kind FROM skills ORDER BY name`) as {
+			name: string;
+			kind: string;
+		}[];
+
+	test("a legacy row becomes written, a linked row is left alone, and the store reads it", async () => {
+		await migrate(sql, SkillStore.migrations(TEST_GUILD));
+		expect(await kinds()).toEqual([
+			{ name: "linked-one", kind: "linked" },
+			{ name: "notes", kind: "written" },
+		]);
+		const store = await SkillStore.attach(sql, TEST_GUILD);
+		expect(store.skill("notes")?.kind).toBe("written");
+	});
+
+	test("running the migration again changes nothing", async () => {
+		await migrate(sql, SkillStore.migrations(TEST_GUILD));
+		const before = await kinds();
+		await migrate(sql, SkillStore.migrations(TEST_GUILD));
+		expect(await kinds()).toEqual(before);
+	});
+});

package/src/core/modules/skills/skill-link.ts

@@ -0,0 +1,69 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { isAbsolute, join, relative as relativePath, resolve } from "node:path";
+import { AgentError } from "../../domain/errors.ts";
+import { checkRepoName } from "./repo-name.ts";
+import { checkSkillName, readSkillFile } from "./skill-rules.ts";
+
+/**
+ * The skills a link would register: the one at a repository path, or every child folder with a
+ * SKILL.md (behavior 15). Throws one error listing every problem, so nothing is half linked.
+ */
+export function planLinkedSkills(
+	reposDir: string,
+	repo: string,
+	path: string,
+	checkFreeName: (name: string) => void,
+): { name: string; repo: string; path: string }[] {
+	checkRepoName(repo);
+	const repoDir = join(reposDir, repo);
+	if (!existsSync(join(repoDir, ".git")))
+		throw new AgentError(
+			`${repo} is not a managed repository; add it with repo_add first.`,
+		);
+	const relative = relativePath(repoDir, resolve(repoDir, path.trim()));
+	if (relative.startsWith("..") || isAbsolute(relative))
+		throw new AgentError(`The path must stay inside ${repo}.`);
+	const dir = join(repoDir, relative);
+	if (!existsSync(dir) || !statSync(dir).isDirectory())
+		throw new AgentError(`${repo} has no folder ${relative || "."}.`);
+	const folders = existsSync(join(dir, "SKILL.md"))
+		? [relative]
+		: readdirSync(dir, { withFileTypes: true })
+				.filter(
+					(entry) =>
+						entry.isDirectory() &&
+						existsSync(join(dir, entry.name, "SKILL.md")),
+				)
+				.map((entry) => (relative ? `${relative}/${entry.name}` : entry.name))
+				.sort();
+	if (folders.length === 0)
+		throw new AgentError(
+			`${repo}:${relative || "."} has no SKILL.md, nor any folder with one.`,
+		);
+	const entries: { name: string; repo: string; path: string }[] = [];
+	const problems: string[] = [];
+	for (const folder of folders) {
+		const read = readSkillFile(join(repoDir, folder, "SKILL.md"));
+		if ("error" in read) {
+			problems.push(`${folder}: ${read.error}`);
+			continue;
+		}
+		try {
+			checkSkillName(read.name);
+			checkFreeName(read.name);
+		} catch (error) {
+			problems.push(`${folder}: ${(error as Error).message}`);
+			continue;
+		}
+		entries.push({ name: read.name, repo, path: folder });
+	}
+	const names = entries.map((e) => e.name);
+	const twice = names.filter((name, i) => names.indexOf(name) !== i);
+	if (twice.length > 0)
+		problems.push(`names used twice: ${[...new Set(twice)].join(", ")}`);
+	if (problems.length > 0)
+		throw new AgentError(
+			`Nothing was linked:\n${problems.map((p) => `- ${p}`).join("\n")}`,
+		);
+	return entries;
+}