@stage-labs/metro 0.1.0-beta.32 → 0.1.0-beta.321

package/runtime/node_modules/@metro-labs/daemon/src/claude/setup-api.ts

@@ -0,0 +1,114 @@
+import type { IncomingMessage } from 'node:http';
+import { isRecord } from '@metro-labs/core/is-record';
+import { ApiError } from '@metro-labs/http/api-error';
+import { readJsonBody } from '@metro-labs/http/api-http';
+import {
+  claudeSetupStatus,
+  ensureClaudeSetup,
+  isPermissionMode,
+  liveEvents,
+  permissionMode,
+  setLiveEvents,
+  setMemoryRoutine,
+  setPermissionMode,
+  setPrivacy,
+  setSystemPrompt,
+  systemPrompt,
+  SYSTEM_PROMPT_MAX,
+  type PermissionMode,
+  type SetupDeps,
+} from './setup.js';
+import { assertSessionStopped, type SessionDeps } from './session.js';
+import { tryMemoryJob } from './memory-routine.js';
+
+const SETUP_BODY_MAX = SYSTEM_PROMPT_MAX * 2;
+
+export interface SetupApiDeps {
+  session?: SessionDeps;
+  setup?: SetupDeps;
+  liveEvents?: (on: boolean) => void;
+  memoryJob?: (on: boolean) => void;
+}
+
+interface SetupChange {
+  privacy?: boolean;
+  permissionMode?: PermissionMode;
+  systemPrompt?: string;
+  liveEvents?: boolean;
+  memoryRoutine?: boolean;
+}
+
+function promptChange(raw: unknown): string | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw !== 'string') throw new ApiError('systemPrompt must be text', 400);
+  if (Buffer.byteLength(raw) > SYSTEM_PROMPT_MAX) throw new ApiError(`systemPrompt must be under ${String(SYSTEM_PROMPT_MAX / 1024)} KiB`, 400);
+  return raw;
+}
+
+function flagChange(raw: unknown, name: string): boolean | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw !== 'boolean') throw new ApiError(`${name} must be true or false`, 400);
+  return raw;
+}
+
+function modeChange(raw: unknown): PermissionMode | undefined {
+  if (raw === undefined) return undefined;
+  if (!isPermissionMode(raw)) throw new ApiError('permissionMode must be auto or bypass', 400);
+  return raw;
+}
+
+function setupChange(body: unknown): SetupChange {
+  if (!isRecord(body)) throw new ApiError('a body is required', 400);
+  const change: SetupChange = {
+    privacy: flagChange(body.privacy, 'privacy'),
+    permissionMode: modeChange(body.permissionMode),
+    systemPrompt: promptChange(body.systemPrompt),
+    liveEvents: flagChange(body.liveEvents, 'liveEvents'),
+    memoryRoutine: flagChange(body.memoryRoutine, 'memoryRoutine'),
+  };
+  const given = Object.fromEntries(Object.entries(change).filter(([, value]) => value !== undefined)) as SetupChange;
+  if (Object.keys(given).length === 0) throw new ApiError('nothing to change', 400);
+  return given;
+}
+
+function changesSession(change: SetupChange, agents: string | undefined): boolean {
+  return (change.permissionMode !== undefined && change.permissionMode !== permissionMode(agents))
+    || (change.systemPrompt !== undefined && change.systemPrompt.trim() !== systemPrompt(agents));
+}
+
+function applyLiveEvents(on: boolean, deps: SetupApiDeps): void {
+  const agents = deps.setup?.agents;
+  if (on !== liveEvents(agents)) setLiveEvents(on, agents);
+  deps.liveEvents?.(on);
+}
+
+function applyMemoryRoutine(on: boolean, deps: SetupApiDeps): void {
+  setMemoryRoutine(on, deps.setup?.agents);
+  (deps.memoryJob ?? tryMemoryJob)(on);
+}
+
+function saveSessionSettings(change: SetupChange, deps: SetupApiDeps): void {
+  const agents = deps.setup?.agents;
+  if (changesSession(change, agents)) assertSessionStopped({ ...deps.session, agents: deps.session?.agents ?? agents });
+  if (change.permissionMode !== undefined) setPermissionMode(change.permissionMode, agents);
+  if (change.systemPrompt !== undefined) setSystemPrompt(change.systemPrompt, agents);
+}
+
+function applySetupChange(change: SetupChange, deps: SetupApiDeps): void {
+  const setup = deps.setup ?? {};
+  saveSessionSettings(change, deps);
+  if (change.privacy !== undefined) setPrivacy(change.privacy, setup.agents);
+  if (change.liveEvents !== undefined) applyLiveEvents(change.liveEvents, deps);
+  if (change.memoryRoutine !== undefined) applyMemoryRoutine(change.memoryRoutine, deps);
+  ensureClaudeSetup(setup);
+}
+
+export async function setupAnswer(req: IncomingMessage, deps: SetupApiDeps): Promise<unknown> {
+  const setup = deps.setup ?? {};
+  const method = req.method ?? 'GET';
+  if (method === 'GET') return claudeSetupStatus(setup);
+  if (method !== 'POST') throw new ApiError('method not allowed', 405);
+  const change = setupChange(await readJsonBody(req, SETUP_BODY_MAX));
+  applySetupChange(change, deps);
+  return claudeSetupStatus(setup);
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/setup-state.ts

@@ -0,0 +1,18 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { readJson, writeJson } from '@metro-labs/core/secure-fs';
+
+const STATE_FILE = 'claude-setup.json';
+
+const statePath = (agents: string): string => join(agents, STATE_FILE);
+
+export function readSetupState(agents: string): Record<string, unknown> {
+  const raw = readJson<unknown>(statePath(agents), null);
+  return isRecord(raw) ? raw : {};
+}
+
+export function writeSetupState(agents: string, patch: Record<string, unknown>): void {
+  mkdirSync(agents, { recursive: true });
+  writeJson(statePath(agents), { ...readSetupState(agents), ...patch });
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/setup.ts

@@ -0,0 +1,325 @@
+import { createHash } from 'node:crypto';
+import { rmSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from '../agent-user/agent-fs.js';
+import { join } from 'node:path';
+import { errMsg, log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { writeAtomic } from '@metro-labs/core/secure-fs';
+import { agentsDir } from '../agents/files.js';
+import { moveHome, removeHome, writeHomeText } from '../agent-user/home-fs.js';
+import { claudeDir } from './files.js';
+import { memoryJobStatus, type MemoryJob } from './memory-routine.js';
+import { cliPackageDir, hooksDir, skillsDir } from './cli-files.js';
+import { hasMetroGuard, withMetroHooks } from './hooks.js';
+import { readSetupState, writeSetupState } from './setup-state.js';
+
+export const PRIVACY_ENV: Record<string, string> = {
+  DISABLE_TELEMETRY: '1',
+  DISABLE_ERROR_REPORTING: '1',
+  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
+  CLAUDE_CODE_GB_DISK_CACHE_WHEN_TELEMETRY_OFF: '1',
+};
+export const RETENTION_DAYS = 7;
+const RULES_FILE = 'METRO.md';
+const RULES_SKILL = 'metro';
+const RENAMED_SKILL = 'metro-orchestrator';
+const RENAMED_NAME = /^name:[ \t]*(["']?)metro-orchestrator\1[ \t]*$/m;
+const SYSTEM_PROMPT_FILE = 'system-prompt.md';
+export const SYSTEM_PROMPT_MAX = 64 * 1024;
+
+const WORKER_AGENT = `---
+name: worker
+description: Default execution agent for delegated work. Full tool access and maximum reasoning effort. Use for any substantive task the orchestrator main thread cannot perform itself - reading and writing code, running commands, research, analysis.
+effort: xhigh
+---
+
+You are a worker agent. The main thread that dispatched you is an orchestrator with no file, shell or network access; it can only delegate and relay messages. That means you are where the actual work happens, and the quality of your output is the quality of the result.
+
+Work to completion. Do not hand back a partial answer with a suggestion that someone else finish it; there is no one else. If part of the task is genuinely blocked, complete every other part in full and say plainly what you left undone and why. Before you finish, read your own last paragraph: if it is a plan, a question or a promise about work you have not done, do that work now.
+
+Keep the change to what the task asks for. A pre-existing bug, a performance problem or behaviour the task does not mention is a follow-up to report at the end, not something to fix now, unless the requested behaviour cannot work without it. Where the task is ambiguous, build the reading its wording and the surrounding code support best, and state that assumption. Commit tests only where the task asks for them or the repository already keeps tests for that kind of change, sized like the neighbouring test files; scratch checks you used to verify yourself need not be kept. This is about extras only: every behaviour the task does ask for, implement completely.
+
+Never call AskUserQuestion or ExitPlanMode. They are blocked by policy, because nobody is watching the terminal around the clock and a blocking prompt stalls indefinitely. When you hit an ambiguity: do everything that does not depend on it, then choose the most reasonable interpretation, state the assumption explicitly in your report, and continue.
+
+Your final message is a report to the orchestrator, not a message to a human. It gets relayed onward, so make it self-contained and concise. Lead with the outcome. Include concrete evidence, command output, file paths with line numbers, test results, for anything you claim to have verified. Report failures faithfully: if a test failed, say so and show the output; if you skipped a step, say that too.
+`;
+
+export interface SetupDeps {
+  dir?: string;
+  agents?: string;
+  cli?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+export type Placed = 'written' | 'present' | 'updated' | 'missing';
+export type SettingsOutcome = 'written' | 'unchanged' | 'unreadable';
+
+export interface SetupReport {
+  privacy: boolean;
+  guard: boolean;
+  worker: Placed;
+  skill: Placed;
+  stage: Placed;
+  memory: Placed;
+  settings: SettingsOutcome;
+}
+
+export interface SetupStatus {
+  privacy: boolean;
+  permissionMode: PermissionMode;
+  systemPrompt: string;
+  liveEvents: boolean;
+  memoryRoutine: boolean;
+  memoryJob: MemoryJob;
+  guard: boolean;
+  worker: boolean;
+  skill: boolean;
+  stage: boolean;
+  memory: boolean;
+  privacyApplied: boolean;
+  retentionDays: number | null;
+}
+
+const PERMISSION_MODES = ['auto', 'bypass'] as const;
+export type PermissionMode = (typeof PERMISSION_MODES)[number];
+
+const privacyEnabled = (agents = agentsDir()): boolean => readSetupState(agents).privacy !== false;
+
+export function setPrivacy(enabled: boolean, agents = agentsDir()): void {
+  writeSetupState(agents, { privacy: enabled });
+}
+
+export const isPermissionMode = (value: unknown): value is PermissionMode => PERMISSION_MODES.some((m) => m === value);
+
+export function permissionMode(agents = agentsDir()): PermissionMode {
+  const mode = readSetupState(agents).permissionMode;
+  return isPermissionMode(mode) ? mode : 'auto';
+}
+
+export function setPermissionMode(mode: PermissionMode, agents = agentsDir()): void {
+  writeSetupState(agents, { permissionMode: mode });
+}
+
+export const liveEvents = (agents = agentsDir()): boolean => readSetupState(agents).liveEvents !== false;
+
+export function setLiveEvents(on: boolean, agents = agentsDir()): void {
+  writeSetupState(agents, { liveEvents: on });
+}
+
+export const memoryRoutine = (agents = agentsDir()): boolean => readSetupState(agents).memoryRoutine !== false;
+
+export function setMemoryRoutine(on: boolean, agents = agentsDir()): void {
+  writeSetupState(agents, { memoryRoutine: on });
+}
+
+const promptPath = (agents: string): string => join(agents, SYSTEM_PROMPT_FILE);
+
+export function systemPrompt(agents = agentsDir()): string {
+  const path = promptPath(agents);
+  if (!existsSync(path)) return '';
+  return readFileSync(path, 'utf8').trim();
+}
+
+export function setSystemPrompt(text: string, agents = agentsDir()): void {
+  const trimmed = text.trim();
+  if (trimmed === '') {
+    rmSync(promptPath(agents), { force: true });
+    return;
+  }
+  writeAtomic(promptPath(agents), `${trimmed}\n`, 0o600);
+}
+
+const PRIOR_WORKER: ReadonlySet<string> = new Set(['08a0cd8710df285d6512245246bb8b658b7cfc7f3e89490514ee5376779eb2ef']);
+const PRIOR_METRO: ReadonlySet<string> = new Set([
+  '0b3d122ed95beff09d579cf912cd4238e1db524c41fce4b314de57d6ff5908ad',
+  '36f4fb57f231a119d717b5e3d6ccb654f94960fcca708683f376679aead8df25',
+  '3840bc50253e51f431691376cf29a925b8245d87b77b8b20804a159e378a6e67',
+  'e6b59eba825b4568dfa9ace5049fd9568a2e10d731719976ad2657084fd4e5f9',
+  '5ce3f76d610aae91adc922d0edc6c8be1f27aa2fec4a5e3a6d6231a04fb9310b',
+  'b910597d24f31fa479b130a2545f94dd23684d802d99e36b637fc57c818a33be',
+  'd3f7ed0f5175b9a7a77f06f6204ae0020369d0c8f6e2724196bb3c5822d4d8ba',
+  '587a1334f91a8b61541573cef16eaf44fbe63049a8d8b461fa9f5cc55bacbcb8',
+  '256c711a6175266c216e32c88b7190d0f98f5e6b702abe03220b422aba426574',
+  '9e164a956437d60d30ea1984115a17d303940d191f5efed04954f244fc89d48f',
+  '8b6d7c5a9bc8d02d5e3ae5e5931b36aba9f3d0eb7fd38b371294c2abaa0c94ee',
+]);
+const PRIOR_STAGE: ReadonlySet<string> = new Set([
+  'dd7d30474765de3865ddc87c1cf3220161ded09502027cdff18597e5df0aab43',
+  '47439ecbe661ca70471a6839ab30a963714c296ad8c14ca23c6eebc3929038cc',
+  'e3b8f9bbdb205311bc643aaf91d9d903a91204fd5b55ca949b85cdfa6fd00136',
+  '08a30f5cd5cf8013ab70c1fa9e1109018c0337552296a8efe5c0cf543b284991',
+  'f87e9494ea6151d140b742c1b88b4f435ae653559be641fddc2160cd24dd4e1b',
+  'cb4307b016855c1a09d48bc8b3924a3080bd78b205963df3d6f20401d0486df9',
+  'd25a8575b1c27ee725ff3a3ec6e1ba42aebd08ba545012c4807c072627c5dd4a',
+  'f2be51c5290d2e61b47f10c379fa45d051a59a6b3f06d99174c2a170074bc8f5',
+  '4c727aa110c9023371cfb364f3304ad9db22cdf2501208ef1e42e6ccc245b00f',
+  'f3901d8a4537441b1d7fe8e4073322a97b779472df6b4a8e0f2091ab5ab0ae09',
+  'af22c346df478fd249cc6931d4cf1dab4e091682e422f1bd27af0a08781e189d',
+]);
+const PRIOR_MEMORY: ReadonlySet<string> = new Set(['08795399635c8cdec2b50cb4e336f89ae880f3997ae52560ef647a9cdc8f1b08']);
+
+interface ShippedSkill {
+  name: string;
+  file: string;
+  prior: ReadonlySet<string>;
+}
+
+const METRO_SKILL: ShippedSkill = { name: RULES_SKILL, file: RULES_FILE, prior: PRIOR_METRO };
+const STAGE_SKILL: ShippedSkill = { name: 'stage', file: 'STAGE.md', prior: PRIOR_STAGE };
+const MEMORY_SKILL: ShippedSkill = { name: 'memory', file: 'MEMORY.md', prior: PRIOR_MEMORY };
+
+const digest = (text: string): string => createHash('sha256').update(text).digest('hex');
+
+export function placeFile(path: string, text: string, prior: ReadonlySet<string> = new Set()): Placed {
+  if (!existsSync(path)) {
+    writeHomeText(path, text, 0o644);
+    return 'written';
+  }
+  const current = readFileSync(path, 'utf8');
+  if (current === text || !prior.has(digest(current))) return 'present';
+  writeHomeText(path, text, 0o644);
+  return 'updated';
+}
+
+function readSettings(path: string): Record<string, unknown> | null {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function withPrivacy(settings: Record<string, unknown>, enabled: boolean): Record<string, unknown> {
+  const current = isRecord(settings.env) ? settings.env : {};
+  if (enabled)
+    return { ...settings, env: { ...current, ...PRIVACY_ENV }, cleanupPeriodDays: settings.cleanupPeriodDays ?? RETENTION_DAYS };
+  const env = Object.fromEntries(Object.entries(current).filter(([key]) => !(key in PRIVACY_ENV)));
+  const rest = Object.fromEntries(Object.entries(settings).filter(([key]) => key !== 'env'));
+  return Object.keys(env).length === 0 ? rest : { ...rest, env };
+}
+
+function mergeSettings(dir: string, change: (settings: Record<string, unknown>) => Record<string, unknown>): SettingsOutcome {
+  const path = join(dir, 'settings.json');
+  const current = readSettings(path);
+  if (current === null) return 'unreadable';
+  const next = change(current);
+  if (existsSync(path) && JSON.stringify(next) === JSON.stringify(current)) return 'unchanged';
+  writeHomeText(path, `${JSON.stringify(next, null, 2)}\n`, existsSync(path) ? statSync(path).mode & 0o777 : 0o644);
+  return 'written';
+}
+
+interface SettingsApplied {
+  settings: SettingsOutcome;
+  guard: boolean;
+}
+
+const MODELS_KEYS = new Set(['availableModels', 'enforceAvailableModels']);
+
+const withoutMetroModels = (settings: Record<string, unknown>, metroWrote: boolean): Record<string, unknown> =>
+  metroWrote ? Object.fromEntries(Object.entries(settings).filter(([key]) => !MODELS_KEYS.has(key))) : settings;
+
+function applySettings(dir: string, agents: string, privacy: boolean, hooks: string | null): SettingsApplied {
+  const metroModels = readSetupState(agents).modelsByMetro === true;
+  let guard = false;
+  const settings = mergeSettings(dir, (current) => {
+    const next = withPrivacy(withoutMetroModels(current, metroModels), privacy);
+    const hooked = hooks === null ? null : withMetroHooks(next, hooks);
+    if (hooks !== null && hooked === null)
+      log.warn({ path: join(dir, 'settings.json') }, 'claude-setup: the hooks in settings.json are not in the shape Claude Code reads, so metro did not add its own');
+    guard = hasMetroGuard(hooked ?? next);
+    return hooked ?? next;
+  });
+  if (metroModels && settings !== 'unreadable') writeSetupState(agents, { modelsByMetro: false });
+  return { settings, guard };
+}
+
+const skillPath = (dir: string, name: string): string => join(dir, 'skills', name, 'SKILL.md');
+const workerPath = (dir: string): string => join(dir, 'agents', 'worker.md');
+
+function placeSkill(dir: string, skills: string, skill: ShippedSkill): Placed {
+  const source = join(skills, skill.file);
+  if (!existsSync(source)) return 'missing';
+  return placeFile(skillPath(dir, skill.name), readFileSync(source, 'utf8'), skill.prior);
+}
+
+function moveRenamedSkill(dir: string): void {
+  const from = join(dir, 'skills', RENAMED_SKILL);
+  const old = skillPath(dir, RENAMED_SKILL);
+  if (!existsSync(old)) return;
+  const shipped = PRIOR_METRO.has(digest(readFileSync(old, 'utf8')));
+  if (existsSync(join(dir, 'skills', RULES_SKILL))) {
+    if (shipped) removeHome(from, true);
+    return;
+  }
+  moveHome(from, join(dir, 'skills', RULES_SKILL));
+  log.info({ from, shipped }, 'claude-setup: moved the metro-orchestrator skill to metro');
+  if (shipped) return;
+  const path = skillPath(dir, RULES_SKILL);
+  const text = readFileSync(path, 'utf8');
+  const renamed = text.replace(RENAMED_NAME, `name: ${RULES_SKILL}`);
+  if (renamed !== text) writeHomeText(path, renamed, statSync(path).mode & 0o777);
+}
+
+function tryMoveRenamedSkill(dir: string): void {
+  try {
+    moveRenamedSkill(dir);
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'claude-setup: could not move the metro-orchestrator skill to metro');
+  }
+}
+
+const written = (placed: Placed): boolean => placed === 'written' || placed === 'updated';
+
+export function ensureClaudeSetup(deps: SetupDeps = {}): SetupReport {
+  const dir = deps.dir ?? claudeDir();
+  const agents = deps.agents ?? agentsDir();
+  const privacy = privacyEnabled(agents);
+  const cli = deps.cli ?? cliPackageDir(deps.env);
+  const hooks = hooksDir(cli);
+  tryMoveRenamedSkill(dir);
+  const worker = placeFile(workerPath(dir), WORKER_AGENT, PRIOR_WORKER);
+  const skills = skillsDir(cli);
+  const skill = placeSkill(dir, skills, METRO_SKILL);
+  const stage = placeSkill(dir, skills, STAGE_SKILL);
+  const memory = placeSkill(dir, skills, MEMORY_SKILL);
+  const applied = applySettings(dir, agents, privacy, hooks);
+  const report: SetupReport = { privacy, guard: applied.guard, worker, skill, stage, memory, settings: applied.settings };
+  if ([report.worker, report.skill, report.stage, report.memory].some(written) || report.settings === 'written')
+    log.info(report, 'claude-setup: applied the Claude Code setup for a metro box');
+  if (report.settings === 'unreadable') log.warn({ path: join(dir, 'settings.json') }, 'claude-setup: settings.json is not valid JSON, so the privacy settings and metro hooks were not written');
+  if (hooks === null) log.warn({ cli }, 'claude-setup: metro hooks were not found next to the CLI, so the guard and the standing rules are not in settings.json');
+  return report;
+}
+
+export function claudeSetupStatus(deps: SetupDeps = {}): SetupStatus {
+  const dir = deps.dir ?? claudeDir();
+  const agents = deps.agents ?? agentsDir();
+  const settings = readSettings(join(dir, 'settings.json'));
+  const env = settings !== null && isRecord(settings.env) ? settings.env : {};
+  const days = settings?.cleanupPeriodDays;
+  return {
+    privacy: privacyEnabled(agents),
+    permissionMode: permissionMode(agents),
+    systemPrompt: systemPrompt(agents),
+    liveEvents: liveEvents(agents),
+    memoryRoutine: memoryRoutine(agents),
+    memoryJob: memoryJobStatus(),
+    guard: hasMetroGuard(settings),
+    worker: existsSync(workerPath(dir)),
+    skill: existsSync(skillPath(dir, METRO_SKILL.name)),
+    stage: existsSync(skillPath(dir, STAGE_SKILL.name)),
+    memory: existsSync(skillPath(dir, MEMORY_SKILL.name)),
+    privacyApplied: Object.keys(PRIVACY_ENV).every((key) => env[key] === '1'),
+    retentionDays: typeof days === 'number' ? days : null,
+  };
+}
+
+export function tryClaudeSetup(deps: SetupDeps = {}): void {
+  try {
+    ensureClaudeSetup(deps);
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'claude-setup: could not apply the Claude Code setup');
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/skills.ts

@@ -0,0 +1,123 @@
+import { existsSync, readdirNames, readFileSync, statSync } from '../agent-user/agent-fs.js';
+import { basename, dirname, join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { claudeDir } from './files.js';
+import { removeHome, writeHomeText } from '../agent-user/home-fs.js';
+
+const SKILL_MAX = 256 * 1024;
+const SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const FILE = 'SKILL.md';
+const DEFAULT_MODE = 0o644;
+const SUMMARY_MAX = 300;
+
+export interface ClaudeSkill {
+  id: string;
+  name: string;
+  title: string;
+  description: string;
+  path: string;
+  editable: boolean;
+  updatedAt: string | null;
+  managed?: boolean;
+  shadowed?: boolean;
+  github?: { repository: string; commit: string; folder: string };
+}
+
+const frontmatterField = (text: string, field: string): string => {
+  const head = text.startsWith('---') ? text.slice(3, text.indexOf('\n---', 3)) : '';
+  for (const line of head.split('\n')) {
+    const at = line.indexOf(':');
+    if (at > 0 && line.slice(0, at).trim() === field) return line.slice(at + 1).trim().replace(/^["']|["']$/g, '').slice(0, SUMMARY_MAX);
+  }
+  return '';
+};
+
+function entryOf(name: string, path: string): ClaudeSkill {
+  const stat = statSync(path);
+  const editable = stat.size <= SKILL_MAX;
+  const text = editable ? readFileSync(path, 'utf8') : '';
+  return {
+    id: `user:${name}`,
+    name,
+    title: frontmatterField(text, 'name') || name,
+    description: frontmatterField(text, 'description'),
+    path,
+    editable,
+    updatedAt: stat.mtime.toISOString(),
+  };
+}
+
+const userSkillsRoot = (dir: string): string => join(dir, 'skills');
+
+function isFolder(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function listClaudeSkills(dir = claudeDir()): ClaudeSkill[] {
+  const root = userSkillsRoot(dir);
+  if (!existsSync(root)) return [];
+  const out: ClaudeSkill[] = [];
+  for (const name of readdirNames(root)) {
+    if (!SKILL_NAME_RE.test(name) || !isFolder(join(root, name))) continue;
+    const path = join(root, name, FILE);
+    if (existsSync(path)) out.push(entryOf(name, path));
+  }
+  return out.sort((a, b) => (b.updatedAt ?? '').localeCompare(a.updatedAt ?? '') || a.name.localeCompare(b.name));
+}
+
+function found(id: string, dir: string): ClaudeSkill {
+  const skill = listClaudeSkills(dir).find((entry) => entry.id === id);
+  if (skill === undefined) throw new ApiError('no such skill', 404);
+  return skill;
+}
+
+export function readClaudeSkill(id: string, dir = claudeDir()): ClaudeSkill & { text: string } {
+  const skill = found(id, dir);
+  return { ...skill, text: skill.editable ? readFileSync(skill.path, 'utf8') : '' };
+}
+
+function assertText(text: string): void {
+  if (text.length > SKILL_MAX) throw new ApiError('that is more text than a skill may hold', 413);
+  if (text.trim() === '') throw new ApiError('a skill needs some text', 400);
+}
+
+export function writeClaudeSkill(
+  id: string,
+  text: string,
+  seenAt: string | null | undefined,
+  dir = claudeDir(),
+): ClaudeSkill {
+  const skill = found(id, dir);
+  if (!skill.editable) throw new ApiError('that skill is too large to edit here', 409);
+  assertText(text);
+  if (seenAt !== undefined && seenAt !== skill.updatedAt)
+    throw new ApiError('that skill changed on disk since you opened it; reload it before saving', 409);
+  writeHomeText(skill.path, text, DEFAULT_MODE);
+  return entryOf(skill.name, skill.path);
+}
+
+const skillTemplate = (name: string): string =>
+  ['---', `name: ${name}`, 'description: what this skill does, and when Claude should reach for it', '---', '', `# ${name}`, '', 'Write the instructions here.', ''].join('\n');
+
+export function createClaudeSkill(name: string, text: string | undefined, dir = claudeDir()): ClaudeSkill {
+  if (typeof name !== 'string' || !SKILL_NAME_RE.test(name))
+    throw new ApiError('a skill name is lowercase letters, digits and dashes, up to 64 characters', 400);
+  const path = join(userSkillsRoot(dir), name, FILE);
+  if (existsSync(path)) throw new ApiError('a skill by that name already lives there', 409);
+  const body = text === undefined || text.trim() === '' ? skillTemplate(name) : text;
+  assertText(body);
+  writeHomeText(path, body, DEFAULT_MODE);
+  return entryOf(name, path);
+}
+
+export function deleteClaudeSkill(id: string, dir = claudeDir()): string {
+  const skill = found(id, dir);
+  const folder = dirname(skill.path);
+  if (basename(folder) !== skill.name) throw new ApiError('that skill does not live in its own folder', 409);
+  removeHome(folder, true);
+  return id;
+}