@moxxy/core 0.3.0

package/src/setup-agent.ts

@@ -0,0 +1,189 @@
+/**
+ * `setupAgent` — the one-call ergonomic entry to the moxxy runtime.
+ *
+ * Constructing a {@link Session}, registering a mode + provider plugins + tools,
+ * activating a provider, and calling {@link runTurn} is the standard boilerplate.
+ * This wraps all of it in a single SYNCHRONOUS call and hands back a small
+ * {@link Agent} you destructure:
+ *
+ *   import { setupAgent } from '@moxxy/core';
+ *   import defaultMode from '@moxxy/mode-default';
+ *   import openai from '@moxxy/plugin-provider-openai';
+ *
+ *   const { ask, stream, session } = setupAgent({
+ *     plugins: [defaultMode, openai],
+ *     provider: { name: 'openai', config: { apiKey: process.env.OPENAI_API_KEY } },
+ *     tools: [myTool],
+ *   });
+ *
+ *   console.log(await ask('Hello!'));               // final reply text (async)
+ *   for await (const e of stream('Go on…')) { … }   // event stream (async generator)
+ *
+ * Two ways to run a turn: `stream()` is a proper async generator that YIELDS each
+ * {@link MoxxyEvent} as it happens; `ask()`/`collect()` are async — the final
+ * text, or every event. The methods close over the session (no `this`), so
+ * destructuring is safe. `session` is the LIVE session — hot-change blocks
+ * between turns through it (or the `setProvider`/`setMode`/`use`/`addTool` sugar).
+ * It stays block-agnostic: you pass the provider/mode PLUGINS in, so `@moxxy/core`
+ * never depends on a vendor.
+ */
+
+import type { MoxxyEvent, PermissionResolver, Plugin, RunTurnOptions, ToolDef } from '@moxxy/sdk';
+
+import { Session, type SessionOptions } from './session.js';
+import { runTurn, collectTurn } from './run-turn.js';
+import { autoAllowResolver, denyByDefaultResolver } from './permissions/resolvers.js';
+
+export interface SetupAgentOptions {
+  /** Working directory the agent operates in. Defaults to `process.cwd()`. */
+  readonly cwd?: string;
+  /** Plugins to register up front — modes, providers, tool-packs, … (order kept). */
+  readonly plugins?: readonly Plugin[];
+  /** Tools to register directly (sugar over authoring a one-tool plugin). */
+  readonly tools?: readonly ToolDef[];
+  /** Activate a provider after registration: its registered `name` + the config
+   *  its `createClient` needs (e.g. `{ apiKey }`). */
+  readonly provider?: { readonly name: string; readonly config?: Record<string, unknown> };
+  /** Permission policy: `'auto'` (approve every tool call — frictionless headless
+   *  default), `'deny'` (refuse all), or a custom {@link PermissionResolver}. */
+  readonly permissions?: 'auto' | 'deny' | PermissionResolver;
+  /** Any other {@link SessionOptions} (logger, secretResolver, pluginLoader,
+   *  pluginDiscoveryPaths, …). */
+  readonly session?: Omit<SessionOptions, 'cwd' | 'permissionResolver'>;
+}
+
+export interface Agent {
+  /** The underlying live {@link Session} — full control + hot-change escape hatch
+   *  (`session.providers`, `session.tools`, `session.modes`, `session.pluginHost`). */
+  readonly session: Session;
+
+  /** Run one turn as an async generator, YIELDING each event as it happens:
+   *  `for await (const e of stream(prompt)) …`. */
+  stream(prompt: string, opts?: RunTurnOptions): AsyncGenerator<MoxxyEvent, void, void>;
+  /** Run one turn; resolve with the final assistant text (`''` if none). */
+  ask(prompt: string, opts?: RunTurnOptions): Promise<string>;
+  /** Run one turn; resolve with every emitted event. */
+  collect(prompt: string, opts?: RunTurnOptions): Promise<ReadonlyArray<MoxxyEvent>>;
+  /** Discover + load plugins from `node_modules` (and `pluginDiscoveryPaths`).
+   *  Async; resolves with this agent for chaining. */
+  discover(): Promise<Agent>;
+
+  // ---- hot-change sugar (mutates the live session; chainable) ----
+  /** Register another plugin (mode / provider / tool-pack) on the live session. */
+  use(plugin: Plugin): Agent;
+  /** Register a tool on the live session. */
+  addTool(tool: ToolDef): Agent;
+  /** Remove a registered tool by name. */
+  removeTool(name: string): Agent;
+  /** Swap the active provider (and its config) for subsequent turns. */
+  setProvider(name: string, config?: Record<string, unknown>): Agent;
+  /** Swap the active loop strategy (mode) for subsequent turns. */
+  setMode(name: string): Agent;
+}
+
+function resolvePermissions(p: SetupAgentOptions['permissions']): PermissionResolver {
+  if (p === 'deny') return denyByDefaultResolver;
+  if (p === undefined || p === 'auto') return autoAllowResolver;
+  return p;
+}
+
+function finalText(events: ReadonlyArray<MoxxyEvent>): string {
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    const e = events[i]!;
+    if (e.type === 'assistant_message') return e.content;
+  }
+  return '';
+}
+
+/** A reusable, pre-filled chunk of {@link SetupAgentOptions} — e.g. a provider
+ *  "preset" that bundles a provider plugin + the default mode + its config, so
+ *  `setupAgent(openaiPreset({ apiKey }))` is a one-line drop-in. A preset is just
+ *  an options object, so presets compose: pass an array and they merge. */
+export type AgentPreset = SetupAgentOptions;
+
+/** Merge an array of presets into one options object: plugins concatenate
+ *  (de-duped by name, so two presets both bringing the default mode register it
+ *  once), tools concatenate, and the FIRST preset that names a provider wins as
+ *  the active one (the others are still registered, so you can `setProvider` to
+ *  swap). cwd/permissions take the first set; session options shallow-merge. */
+function mergePresets(presets: readonly SetupAgentOptions[]): SetupAgentOptions {
+  const plugins: Plugin[] = [];
+  const seen = new Set<string>();
+  const tools: ToolDef[] = [];
+  let provider: SetupAgentOptions['provider'];
+  let cwd: string | undefined;
+  let permissions: SetupAgentOptions['permissions'];
+  let session: SetupAgentOptions['session'];
+  for (const p of presets) {
+    for (const pl of p.plugins ?? []) {
+      if (seen.has(pl.name)) continue;
+      seen.add(pl.name);
+      plugins.push(pl);
+    }
+    if (p.tools) tools.push(...p.tools);
+    if (!provider && p.provider) provider = p.provider;
+    cwd ??= p.cwd;
+    permissions ??= p.permissions;
+    if (p.session) session = { ...session, ...p.session };
+  }
+  return { plugins, tools, provider, cwd, permissions, session };
+}
+
+/**
+ * Build a ready-to-run {@link Agent}. Synchronous — destructure the result.
+ * Accepts a full options object, a single {@link AgentPreset}, or an ARRAY of
+ * presets that are merged (see {@link mergePresets}):
+ *
+ *   setupAgent(openaiPreset({ apiKey }))
+ *   setupAgent([openaiPreset({ apiKey }), anthropicPreset({ apiKey })]) // both; openai active
+ */
+export function setupAgent(input: SetupAgentOptions | readonly SetupAgentOptions[] = {}): Agent {
+  const opts = Array.isArray(input) ? mergePresets(input) : (input as SetupAgentOptions);
+  const session = new Session({
+    cwd: opts.cwd ?? process.cwd(),
+    permissionResolver: resolvePermissions(opts.permissions),
+    ...opts.session,
+  });
+
+  for (const plugin of opts.plugins ?? []) session.pluginHost.registerStatic(plugin);
+  for (const tool of opts.tools ?? []) session.tools.register(tool);
+  if (opts.provider) session.providers.setActive(opts.provider.name, opts.provider.config);
+
+  const agent: Agent = {
+    session,
+    async *stream(prompt, runOpts) {
+      yield* runTurn(session, prompt, runOpts);
+    },
+    async ask(prompt, runOpts) {
+      return finalText(await collectTurn(session, prompt, runOpts));
+    },
+    collect(prompt, runOpts) {
+      return collectTurn(session, prompt, runOpts);
+    },
+    async discover() {
+      await session.pluginHost.discoverAndLoad();
+      return agent;
+    },
+    use(plugin) {
+      session.pluginHost.registerStatic(plugin);
+      return agent;
+    },
+    addTool(tool) {
+      session.tools.register(tool);
+      return agent;
+    },
+    removeTool(name) {
+      session.tools.unregister(name);
+      return agent;
+    },
+    setProvider(name, config) {
+      session.providers.setActive(name, config);
+      return agent;
+    },
+    setMode(name) {
+      session.modes.setActive(name);
+      return agent;
+    },
+  };
+  return agent;
+}

package/src/skills/index.ts

@@ -0,0 +1,14 @@
+export { parseSkillFile, parseFrontmatter } from './parse.js';
+export {
+  discoverSkills,
+  defaultUserSkillsDir,
+  defaultProjectSkillsDir,
+  type SkillLoadOptions,
+  type DiscoveredSkill,
+} from './loader.js';
+export {
+  synthesizeSkill,
+  buildSynthesizeSkillPlugin,
+  type SynthesizeOptions,
+  type SynthesizedSkill,
+} from './synthesize.js';

package/src/skills/loader.test.ts

@@ -0,0 +1,102 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { discoverSkills } from './loader.js';
+import { silentLogger } from '../logger.js';
+
+let tmp: string;
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-skills-'));
+});
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+const writeSkill = async (dir: string, name: string, body = '...') => {
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(
+    path.join(dir, `${name}.md`),
+    `---\nname: ${name}\ndescription: skill ${name}\ntriggers: [${name}]\n---\n${body}`,
+  );
+};
+
+describe('discoverSkills', () => {
+  it('loads skills from project, user, plugin, and builtin', async () => {
+    await writeSkill(path.join(tmp, 'project'), 'a-project');
+    await writeSkill(path.join(tmp, 'user'), 'b-user');
+    await writeSkill(path.join(tmp, 'plugin'), 'c-plugin');
+    await writeSkill(path.join(tmp, 'builtin'), 'd-builtin');
+
+    const skills = await discoverSkills({
+      projectDir: path.join(tmp, 'project'),
+      userDir: path.join(tmp, 'user'),
+      pluginDirs: [path.join(tmp, 'plugin')],
+      builtinDir: path.join(tmp, 'builtin'),
+      logger: silentLogger,
+    });
+    const names = skills.map((s) => s.frontmatter.name).sort();
+    expect(names).toEqual(['a-project', 'b-user', 'c-plugin', 'd-builtin']);
+  });
+
+  it('project scope overrides user/builtin with the same skill name', async () => {
+    await writeSkill(path.join(tmp, 'project'), 'shared', 'project body');
+    await writeSkill(path.join(tmp, 'user'), 'shared', 'user body');
+    await writeSkill(path.join(tmp, 'builtin'), 'shared', 'builtin body');
+
+    const skills = await discoverSkills({
+      projectDir: path.join(tmp, 'project'),
+      userDir: path.join(tmp, 'user'),
+      builtinDir: path.join(tmp, 'builtin'),
+      logger: silentLogger,
+    });
+    expect(skills).toHaveLength(1);
+    expect(skills[0]!.scope).toBe('project');
+    expect(skills[0]!.body).toContain('project body');
+  });
+
+  it('silently skips files with invalid frontmatter', async () => {
+    const dir = path.join(tmp, 'project');
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, 'bad.md'), '---\nname: Bad Name\n---\n');
+    const skills = await discoverSkills({ projectDir: dir, userDir: path.join(tmp, 'noop'), logger: silentLogger });
+    expect(skills).toHaveLength(0);
+  });
+
+  it('skips a single unreadable .md but still loads the rest of the tree (u46-5)', async () => {
+    // A permission-denied read used to throw out of loadDir and abort discovery
+    // of every remaining skill in every source. It must now degrade to skipping
+    // just the bad file. (chmod 000 has no teeth as root, so skip there.)
+    if (typeof process.getuid === 'function' && process.getuid() === 0) return;
+    const dir = path.join(tmp, 'project');
+    await writeSkill(dir, 'good-one');
+    const badPath = path.join(dir, 'unreadable.md');
+    await fs.writeFile(
+      badPath,
+      '---\nname: unreadable\ndescription: x\ntriggers: [unreadable]\n---\nbody',
+    );
+    await fs.chmod(badPath, 0o000);
+    try {
+      const skills = await discoverSkills({
+        projectDir: dir,
+        userDir: path.join(tmp, 'noop'),
+        logger: silentLogger,
+      });
+      // The valid skill survives even though a sibling .md was unreadable.
+      expect(skills.map((s) => s.frontmatter.name)).toEqual(['good-one']);
+    } finally {
+      // Restore perms so afterEach rm can clean up.
+      await fs.chmod(badPath, 0o644).catch(() => {});
+    }
+  });
+
+  it('returns empty list when directories do not exist', async () => {
+    const skills = await discoverSkills({
+      projectDir: path.join(tmp, 'no-project'),
+      userDir: path.join(tmp, 'no-user'),
+      logger: silentLogger,
+    });
+    expect(skills).toEqual([]);
+  });
+});

package/src/skills/loader.ts

@@ -0,0 +1,114 @@
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { skillFrontmatterSchema, asSkillId, type Skill, type SkillScope } from '@moxxy/sdk';
+import { parseSkillFile } from './parse.js';
+import type { Logger } from '../logger.js';
+
+export interface SkillLoadOptions {
+  readonly projectDir?: string;
+  readonly userDir?: string;
+  readonly pluginDirs?: ReadonlyArray<string>;
+  readonly builtinDir?: string;
+  readonly logger?: Logger;
+}
+
+export interface DiscoveredSkill extends Skill {
+  readonly scope: SkillScope;
+}
+
+export async function discoverSkills(opts: SkillLoadOptions = {}): Promise<ReadonlyArray<DiscoveredSkill>> {
+  const sources: Array<{ dir: string; scope: SkillScope }> = [];
+  if (opts.builtinDir) sources.push({ dir: opts.builtinDir, scope: 'builtin' });
+  for (const dir of opts.pluginDirs ?? []) sources.push({ dir, scope: 'plugin' });
+  const userDir = opts.userDir ?? defaultUserSkillsDir();
+  sources.push({ dir: userDir, scope: 'user' });
+  if (opts.projectDir) sources.push({ dir: opts.projectDir, scope: 'project' });
+
+  const seenNames = new Map<string, DiscoveredSkill>();
+  for (const source of sources) {
+    const skills = await loadDir(source.dir, source.scope, opts.logger);
+    for (const skill of skills) seenNames.set(skill.frontmatter.name, skill);
+  }
+  return [...seenNames.values()];
+}
+
+async function loadDir(
+  dir: string,
+  scope: SkillScope,
+  logger?: Logger,
+): Promise<ReadonlyArray<DiscoveredSkill>> {
+  let entries: import('node:fs').Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out: DiscoveredSkill[] = [];
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      out.push(...(await loadDir(path.join(dir, entry.name), scope, logger)));
+      continue;
+    }
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const full = path.join(dir, entry.name);
+    let raw: string;
+    try {
+      raw = await fs.readFile(full, 'utf8');
+    } catch (err) {
+      // One unreadable .md (permission, race-deleted, symlink loop) must not
+      // abort discovery of every remaining skill across every source — degrade
+      // to skipping just this file, like the invalid-frontmatter case below.
+      logger?.warn('skill: unreadable file, skipping', {
+        path: full,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      continue;
+    }
+    const { frontmatter, body } = parseSkillFile(raw);
+    const parsed = skillFrontmatterSchema.safeParse(frontmatter);
+    if (!parsed.success) {
+      logger?.warn('skill: invalid frontmatter, skipping', { path: full, issues: parsed.error.issues });
+      continue;
+    }
+    // Auto-derive trigger fallbacks from the skill name when the
+    // frontmatter `triggers:` field is missing/empty. Without this,
+    // user-authored skills (or model-synthesized ones that skipped the
+    // field) have no triggers at all — they're effectively invisible
+    // to the trigger-match router and confusing in /skills listings.
+    // We split the kebab-case name into words and also keep the full
+    // slug as a literal trigger.
+    const fm = parsed.data;
+    const finalTriggers =
+      fm.triggers && fm.triggers.length > 0 ? fm.triggers : deriveTriggers(fm.name);
+    out.push({
+      id: asSkillId(`${scope}/${fm.name}`),
+      path: full,
+      scope,
+      frontmatter: { ...fm, triggers: finalTriggers },
+      body: body.trimEnd(),
+    });
+  }
+  return out;
+}
+
+/**
+ * Derive trigger-like phrases from a kebab-case skill name. Best-effort
+ * fallback for skills whose frontmatter omits the `triggers:` field —
+ * gives the router and `/skills` listing *something* to show.
+ */
+function deriveTriggers(name: string): ReadonlyArray<string> {
+  const parts = name.split('-').filter((p) => p.length > 1);
+  const out = new Set<string>();
+  out.add(name.replace(/-/g, ' '));
+  for (const p of parts) out.add(p);
+  return [...out];
+}
+
+export function defaultUserSkillsDir(): string {
+  return path.join(os.homedir(), '.moxxy', 'skills');
+}
+
+export function defaultProjectSkillsDir(cwd: string): string {
+  return path.join(cwd, '.moxxy', 'skills');
+}

package/src/skills/parse.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import { parseFrontmatter, parseSkillFile } from './parse.js';
+
+describe('parseSkillFile', () => {
+  it('returns empty frontmatter when none present', () => {
+    const { frontmatter, body } = parseSkillFile('hello world');
+    expect(frontmatter).toEqual({});
+    expect(body).toBe('hello world');
+  });
+
+  it('parses simple frontmatter', () => {
+    const { frontmatter, body } = parseSkillFile(`---
+name: foo
+description: bar
+---
+body text`);
+    expect(frontmatter).toEqual({ name: 'foo', description: 'bar' });
+    expect(body.trim()).toBe('body text');
+  });
+
+  it('parses inline arrays', () => {
+    const { frontmatter } = parseSkillFile(`---
+name: foo
+description: d
+triggers: [a, b, "c d"]
+---`);
+    expect(frontmatter.triggers).toEqual(['a', 'b', 'c d']);
+  });
+
+  it('parses block-list arrays', () => {
+    const { frontmatter } = parseSkillFile(`---
+name: foo
+description: d
+allowed-tools:
+  - Read
+  - Edit
+  - Bash
+---`);
+    expect(frontmatter['allowed-tools']).toEqual(['Read', 'Edit', 'Bash']);
+  });
+
+  it('handles quoted strings with colons', () => {
+    const fm = parseFrontmatter(`description: "a: b"`);
+    expect(fm.description).toBe('a: b');
+  });
+
+  it('parses numbers and booleans', () => {
+    const fm = parseFrontmatter(`count: 3\nbig: true\nzero: false`);
+    expect(fm.count).toBe(3);
+    expect(fm.big).toBe(true);
+    expect(fm.zero).toBe(false);
+  });
+
+  it('preserves multiline body with --- fence', () => {
+    const md = `---\nname: foo\ndescription: d\n---\nline 1\n\nline 2`;
+    const { body } = parseSkillFile(md);
+    expect(body).toBe('line 1\n\nline 2');
+  });
+});

package/src/skills/parse.ts

@@ -0,0 +1,11 @@
+// The skill frontmatter parser now lives canonically in @moxxy/sdk
+// (`parseFrontmatterFile`/`parseFrontmatter`), shared with plugin-memory so the
+// previously-copy-pasted copies can't diverge. This module keeps the historical
+// `parseSkillFile`/`ParsedSkillFile` names as thin re-exports.
+import { parseFrontmatterFile, type ParsedFrontmatter } from '@moxxy/sdk';
+
+export type ParsedSkillFile = ParsedFrontmatter;
+
+export const parseSkillFile = parseFrontmatterFile;
+
+export { parseFrontmatter } from '@moxxy/sdk';

package/src/skills/synthesize-draft.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import type { LLMProvider, ProviderEvent } from '@moxxy/sdk';
+import { draftSkill } from './synthesize-draft.js';
+
+/**
+ * `draftSkill` streams the model's output, then unwraps any ```markdown fence
+ * (its private `extractMarkdownBlock`) before parsing frontmatter. These tests
+ * drive that unwrapping end-to-end through the public `draftSkill` entrypoint
+ * with a scripted provider — no real LLM — asserting `raw` is the unwrapped
+ * document and that the frontmatter/body split lines up.
+ */
+
+const FRONTMATTER =
+  '---\nname: demo-skill\ndescription: A demo.\ntriggers: ["a", "b"]\nallowed-tools: [Read]\n---\n# Body\n\n1. Do the thing.\n';
+
+class ScriptedProvider implements LLMProvider {
+  readonly name = 'scripted';
+  readonly models = [
+    { id: 'm1', contextWindow: 100_000, maxOutputTokens: 2000, supportsTools: true, supportsStreaming: true },
+  ];
+  constructor(private readonly events: ReadonlyArray<ProviderEvent>) {}
+  async *stream(): AsyncIterable<ProviderEvent> {
+    for (const e of this.events) yield e;
+  }
+  async countTokens(): Promise<number> {
+    return 0;
+  }
+}
+
+const deltas = (...chunks: string[]): ProviderEvent[] => [
+  { type: 'message_start', model: 'm1' },
+  ...chunks.map((delta) => ({ type: 'text_delta', delta }) as ProviderEvent),
+  { type: 'message_end', stopReason: 'end_turn' },
+];
+
+async function run(events: ProviderEvent[]) {
+  const provider = new ScriptedProvider(events);
+  return draftSkill(provider, 'm1', 'make a demo skill', new AbortController().signal);
+}
+
+describe('draftSkill / extractMarkdownBlock unwrapping', () => {
+  it('returns the raw markdown verbatim when the model emits no code fence', async () => {
+    const draft = await run(deltas(FRONTMATTER));
+    expect(draft.raw).toBe(FRONTMATTER);
+    expect(draft.frontmatter.name).toBe('demo-skill');
+    expect(draft.body).toContain('Do the thing.');
+  });
+
+  it('unwraps a ```markdown fenced block (strips fence + language tag)', async () => {
+    const fenced = '```markdown\n' + FRONTMATTER + '```';
+    const draft = await run(deltas('Sure, here you go:\n', fenced));
+    // The leading prose and the fence markers are stripped; only the inner doc
+    // survives into `raw`, and parses cleanly.
+    expect(draft.raw).toBe(FRONTMATTER);
+    expect(draft.frontmatter.name).toBe('demo-skill');
+  });
+
+  it('unwraps a bare ``` fenced block (no language tag)', async () => {
+    const fenced = '```\n' + FRONTMATTER + '```';
+    const draft = await run(deltas(fenced));
+    expect(draft.raw).toBe(FRONTMATTER);
+  });
+
+  it('extracts the FIRST fenced block when the model wraps and then chatters', async () => {
+    const out = '```md\n' + FRONTMATTER + '```\nLet me know if you want changes!';
+    const draft = await run(deltas(out));
+    expect(draft.raw).toBe(FRONTMATTER);
+    expect(draft.raw).not.toContain('Let me know');
+  });
+
+  it('surfaces a provider error event as a thrown error', async () => {
+    await expect(
+      run([
+        { type: 'message_start', model: 'm1' },
+        { type: 'error', message: 'boom', retryable: false },
+      ]),
+    ).rejects.toThrow(/provider error: boom/);
+  });
+});

package/src/skills/synthesize-draft.ts

@@ -0,0 +1,46 @@
+import type { LLMProvider } from '@moxxy/sdk';
+import { parseSkillFile } from './parse.js';
+
+export interface DraftedSkill {
+  raw: string;
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+const DRAFT_SYSTEM_PROMPT = `You are a skill-author. Output ONLY a Markdown file with YAML frontmatter. No prose outside the Markdown. Frontmatter MUST include:
+- name (kebab-case slug, <=60 chars, lowercase letters/numbers/hyphens only, starting with a letter)
+- description (1 sentence, <=120 chars)
+- triggers (array of 2-5 short phrases the user might say)
+- allowed-tools (array of tool names, e.g. ["Read", "Edit", "Bash"])
+
+The body is the instructions for future invocations. Keep it under 30 lines. Numbered steps preferred.`;
+
+export async function draftSkill(
+  provider: LLMProvider,
+  model: string,
+  intent: string,
+  signal: AbortSignal,
+): Promise<DraftedSkill> {
+  let accumulated = '';
+  for await (const event of provider.stream({
+    model,
+    system: DRAFT_SYSTEM_PROMPT,
+    messages: [{ role: 'user', content: [{ type: 'text', text: `User intent: ${intent}` }] }],
+    maxTokens: 2000,
+    signal,
+  })) {
+    if (event.type === 'text_delta') accumulated += event.delta;
+    if (event.type === 'error') {
+      throw new Error(`synthesizeSkill: provider error: ${event.message}`);
+    }
+  }
+
+  const raw = extractMarkdownBlock(accumulated);
+  const { frontmatter, body } = parseSkillFile(raw);
+  return { raw, frontmatter: frontmatter as Record<string, unknown>, body };
+}
+
+function extractMarkdownBlock(s: string): string {
+  const fence = /```(?:markdown|md)?\n([\s\S]*?)```/.exec(s);
+  return fence ? fence[1]! : s;
+}