roboport 0.0.1

package/skills/index.js

@@ -0,0 +1,1007 @@
+// @bun
+// src/core/agent.ts
+import { z } from "zod";
+
+// src/core/session.ts
+class Turn {
+  queue = [];
+  waiters = [];
+  ended = false;
+  iterated = false;
+  resultPromise;
+  abortController = new AbortController;
+  constructor(runner) {
+    this.resultPromise = runner({
+      emit: (event) => this.emit(event),
+      signal: this.abortController.signal
+    }).then((messages) => {
+      this.close();
+      return messages;
+    }, (error) => {
+      this.close();
+      throw error;
+    });
+    this.resultPromise.catch(() => {});
+  }
+  emit(event) {
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter({ value: event, done: false });
+    } else {
+      this.queue.push(event);
+    }
+  }
+  close() {
+    this.ended = true;
+    while (this.waiters.length > 0) {
+      const waiter = this.waiters.shift();
+      waiter?.({ value: undefined, done: true });
+    }
+  }
+  abort(reason) {
+    this.abortController.abort(reason);
+  }
+  [Symbol.asyncIterator]() {
+    if (this.iterated) {
+      throw new Error("Turn can only be iterated once.");
+    }
+    this.iterated = true;
+    return {
+      next: () => {
+        if (this.queue.length > 0) {
+          const value = this.queue.shift();
+          return Promise.resolve({ value, done: false });
+        }
+        if (this.ended) {
+          return Promise.resolve({
+            value: undefined,
+            done: true
+          });
+        }
+        return new Promise((resolve) => this.waiters.push(resolve));
+      },
+      return: async () => {
+        this.abort("iteration ended");
+        await this.resultPromise.catch(() => {});
+        return {
+          value: undefined,
+          done: true
+        };
+      }
+    };
+  }
+  then(onfulfilled, onrejected) {
+    return this.resultPromise.then(onfulfilled, onrejected);
+  }
+}
+
+class Session {
+  internals;
+  state;
+  constructor(internals, state) {
+    this.internals = internals;
+    this.state = state;
+  }
+  get messages() {
+    return this.state.messages;
+  }
+  send(prompt) {
+    return this.internals.send(prompt);
+  }
+  async close() {
+    await this.internals.close();
+  }
+  async[Symbol.asyncDispose]() {
+    await this.close();
+  }
+}
+
+// src/core/tool.ts
+import * as z4 from "zod/v4/core";
+function hasParseMethod(schema) {
+  return typeof schema === "object" && schema !== null && "parse" in schema && typeof schema.parse === "function";
+}
+
+class Tool {
+  name;
+  description;
+  inputSchema;
+  jsonSchema;
+  execute;
+  deferred;
+  constructor(init) {
+    this.name = init.name;
+    this.description = init.description;
+    this.deferred = init.deferred ?? false;
+    if ("inputSchema" in init) {
+      this.inputSchema = init.inputSchema;
+      this.execute = init.execute;
+    } else {
+      this.jsonSchema = init.jsonSchema;
+      this.execute = init.execute;
+    }
+  }
+  toJsonSchema() {
+    if (this.jsonSchema !== undefined)
+      return this.jsonSchema;
+    if (this.inputSchema === undefined) {
+      throw new Error(`Tool "${this.name}" has neither inputSchema nor jsonSchema.`);
+    }
+    return z4.toJSONSchema(this.inputSchema);
+  }
+  parse(input) {
+    const schema = this.inputSchema;
+    if (!schema)
+      return input;
+    if (hasParseMethod(schema))
+      return schema.parse(input);
+    return z4.parse(schema, input);
+  }
+}
+function createRegistry(tools) {
+  const byName = new Map(tools.map((tool) => [tool.name, tool]));
+  const loadedNames = new Set(tools.filter((tool) => !tool.deferred).map((tool) => tool.name));
+  return {
+    loaded: () => tools.filter((tool) => loadedNames.has(tool.name)),
+    deferred: () => tools.filter((tool) => tool.deferred && !loadedNames.has(tool.name)),
+    load: (names) => {
+      const loaded = [];
+      const missing = [];
+      for (const name of names) {
+        const tool = byName.get(name);
+        if (!tool) {
+          missing.push(name);
+          continue;
+        }
+        loadedNames.add(name);
+        loaded.push(tool);
+      }
+      return { loaded, missing };
+    }
+  };
+}
+
+// src/core/agent.ts
+class Agent {
+  model;
+  system;
+  tools;
+  skills;
+  mcp;
+  cwd;
+  registrations = [];
+  unsubs = [];
+  constructor({
+    model,
+    system,
+    tools,
+    skills,
+    mcp,
+    cwd
+  }) {
+    this.model = model;
+    this.system = system;
+    this.tools = tools;
+    this.skills = skills;
+    this.mcp = mcp ?? [];
+    this.cwd = cwd;
+  }
+  on(trigger, handler) {
+    this.registrations.push({ trigger, handler });
+  }
+  async start() {
+    for (const { trigger, handler } of this.registrations) {
+      const unsub = await trigger.start((event) => {
+        Promise.resolve().then(() => handler(event)).catch((error) => {
+          const message = error instanceof Error ? error.message : String(error);
+          console.error(`[roboport] trigger "${trigger.name}" handler failed: ${message}`);
+        });
+      });
+      this.unsubs.push(unsub);
+    }
+  }
+  async stop() {
+    const unsubs = this.unsubs;
+    this.unsubs = [];
+    await Promise.all(unsubs.map((u) => u()));
+  }
+  buildSystem(allTools) {
+    let system = this.system;
+    if (this.skills.length > 0) {
+      const skillsList = this.skills.map((skill) => `- ${skill.name}: ${skill.description}`).join(`
+`);
+      system = `${system}
+
+# Skills
+The following skills are available. When a task matches one, call the \`Skill\` tool with that skill's name to load its full content before proceeding.
+
+${skillsList}`;
+    }
+    const deferred = allTools.filter((tool) => tool.deferred);
+    if (deferred.length > 0) {
+      const list = deferred.map((tool) => `- ${tool.name}`).join(`
+`);
+      system = `${system}
+
+# Deferred tools
+These tools are available but their schemas are not loaded. Use ToolSearch to load them before calling.
+${list}`;
+    }
+    return system;
+  }
+  buildSkillTool() {
+    const byName = new Map(this.skills.map((skill) => [skill.name, skill]));
+    return new Tool({
+      name: "Skill",
+      description: 'Load the full content of a skill listed under "# Skills" in the system prompt. Call this when you decide a listed skill applies to the current task; the returned content extends your instructions for the rest of the session.',
+      inputSchema: z.object({
+        skill: z.string().describe("Name of the skill to load (must match a listed skill).")
+      }),
+      execute: ({ skill }) => {
+        const found = byName.get(skill);
+        if (!found) {
+          const available = [...byName.keys()].join(", ");
+          throw new Error(`Skill "${skill}" not found. Available: ${available}`);
+        }
+        return `<skill name="${found.name}">
+${found.content}
+</skill>`;
+      }
+    });
+  }
+  session(init) {
+    const initialMessages = init?.messages ? [...init.messages] : [];
+    const sessionCwd = init?.cwd ?? this.cwd ?? process.cwd();
+    const state = {
+      messages: initialMessages,
+      store: new Map
+    };
+    let activeTurn = null;
+    let mcpConnected = false;
+    let allTools = null;
+    let registry = null;
+    let ctx = null;
+    const ensureReady = async () => {
+      if (!allTools || !registry || !ctx) {
+        const mcpToolGroups = await Promise.all(this.mcp.map((mcp) => mcp.connect()));
+        mcpConnected = true;
+        allTools = [
+          ...this.tools,
+          ...mcpToolGroups.flat(),
+          ...this.skills.length > 0 ? [this.buildSkillTool()] : []
+        ];
+        registry = createRegistry(allTools);
+        ctx = {
+          complete: async (p) => {
+            const response = await this.model.createMessage({
+              messages: [{ role: "user", content: p }]
+            });
+            return response.content.filter((block) => block.type === "text").map((block) => block.text).join(`
+`);
+          },
+          searchWeb: (query, opts) => this.model.searchWeb(query, opts),
+          session: state,
+          tools: registry,
+          cwd: sessionCwd
+        };
+        if (state.messages.length === 0 || state.messages[0]?.role !== "system") {
+          state.messages.unshift({
+            role: "system",
+            content: this.buildSystem(allTools)
+          });
+        }
+      }
+      return { tools: allTools, registry, ctx };
+    };
+    const internals = {
+      send: (prompt) => {
+        if (activeTurn !== null) {
+          throw new Error("Session.send() called while another turn is in flight.");
+        }
+        const turn = new Turn(async (turnCtx) => {
+          try {
+            const ready = await ensureReady();
+            state.messages.push(toUserMessage(prompt));
+            await runAgentLoop({
+              model: this.model,
+              state,
+              registry: ready.registry,
+              ctx: ready.ctx,
+              emit: turnCtx.emit,
+              signal: turnCtx.signal
+            });
+            return [...state.messages];
+          } finally {
+            activeTurn = null;
+          }
+        });
+        activeTurn = turn;
+        return turn;
+      },
+      close: async () => {
+        const pending = activeTurn;
+        if (pending) {
+          pending.abort("session closed");
+          await Promise.resolve(pending).catch(() => {});
+        }
+        if (mcpConnected) {
+          await Promise.all(this.mcp.map((mcp) => mcp.disconnect()));
+          mcpConnected = false;
+        }
+      }
+    };
+    return new Session(internals, state);
+  }
+}
+function toUserMessage(prompt) {
+  if (typeof prompt === "string")
+    return { role: "user", content: prompt };
+  return { role: "user", content: prompt };
+}
+async function runAgentLoop({
+  model,
+  state,
+  registry,
+  ctx,
+  emit,
+  signal
+}) {
+  while (true) {
+    if (signal.aborted)
+      break;
+    const active = registry.loaded();
+    const toolByName = new Map(active.map((tool) => [tool.name, tool]));
+    emit({ type: "message-start" });
+    const assistantContent = [];
+    let stopReason = "end_turn";
+    let usage = { inputTokens: 0, outputTokens: 0 };
+    try {
+      for await (const event of model.streamMessage({
+        messages: state.messages,
+        tools: active,
+        signal
+      })) {
+        switch (event.type) {
+          case "text-delta":
+            emit({ type: "text-delta", text: event.text });
+            break;
+          case "text-end":
+            assistantContent.push({ type: "text", text: event.text });
+            emit({ type: "text", text: event.text });
+            break;
+          case "thinking-delta":
+            emit({ type: "thinking-delta", text: event.text });
+            break;
+          case "thinking-end":
+            assistantContent.push({
+              type: "thinking",
+              text: event.text,
+              ...event.signature !== undefined ? { signature: event.signature } : {},
+              ...event.redactedData !== undefined ? { redactedData: event.redactedData } : {}
+            });
+            emit({
+              type: "thinking",
+              text: event.text,
+              ...event.signature !== undefined ? { signature: event.signature } : {}
+            });
+            break;
+          case "tool-call":
+            assistantContent.push({
+              type: "tool-call",
+              toolCallId: event.toolCallId,
+              toolName: event.toolName,
+              input: event.input
+            });
+            emit({
+              type: "tool-call",
+              toolCallId: event.toolCallId,
+              toolName: event.toolName,
+              input: event.input
+            });
+            break;
+          case "message-end":
+            stopReason = event.stopReason;
+            usage = event.usage;
+            break;
+          default:
+            break;
+        }
+      }
+    } catch (error) {
+      if (signal.aborted) {
+        state.messages.push({ role: "assistant", content: assistantContent });
+        break;
+      }
+      const err = error instanceof Error ? error : new Error(String(error));
+      emit({ type: "error", error: err });
+      throw err;
+    }
+    state.messages.push({ role: "assistant", content: assistantContent });
+    emit({ type: "message-end", usage });
+    if (stopReason !== "tool_use") {
+      emit({ type: "turn-end" });
+      break;
+    }
+    const toolCalls = assistantContent.filter((block) => block.type === "tool-call");
+    const results = [];
+    for (const call of toolCalls) {
+      if (signal.aborted)
+        break;
+      const tool = toolByName.get(call.toolName);
+      const result = await runTool(tool, call, ctx);
+      results.push(result);
+      emit({
+        type: "tool-result",
+        toolCallId: result.toolCallId,
+        toolName: result.toolName,
+        output: result.output,
+        isError: typeof result.output === "string" ? result.output.startsWith("Error:") : false
+      });
+    }
+    state.messages.push({ role: "tool", content: results });
+    if (signal.aborted)
+      break;
+  }
+}
+async function runTool(tool, call, ctx) {
+  if (!tool) {
+    return {
+      type: "tool-result",
+      toolCallId: call.toolCallId,
+      toolName: call.toolName,
+      output: `Error: tool "${call.toolName}" not found`
+    };
+  }
+  try {
+    const parsed = tool.parse(call.input);
+    const output = await tool.execute(parsed, ctx);
+    return {
+      type: "tool-result",
+      toolCallId: call.toolCallId,
+      toolName: call.toolName,
+      output
+    };
+  } catch (error) {
+    return {
+      type: "tool-result",
+      toolCallId: call.toolCallId,
+      toolName: call.toolName,
+      output: `Error: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+}
+
+// src/core/model.ts
+class Model {
+  async createMessage(params) {
+    const content = [];
+    let id = "";
+    let stopReason = "end_turn";
+    let usage = { inputTokens: 0, outputTokens: 0 };
+    for await (const event of this.streamMessage(params)) {
+      switch (event.type) {
+        case "text-end":
+          content.push({ type: "text", text: event.text });
+          break;
+        case "thinking-end":
+          content.push({
+            type: "thinking",
+            text: event.text,
+            ...event.signature !== undefined ? { signature: event.signature } : {},
+            ...event.redactedData !== undefined ? { redactedData: event.redactedData } : {}
+          });
+          break;
+        case "tool-call":
+          content.push({
+            type: "tool-call",
+            toolCallId: event.toolCallId,
+            toolName: event.toolName,
+            input: event.input
+          });
+          break;
+        case "message-end":
+          id = event.id;
+          stopReason = event.stopReason;
+          usage = event.usage;
+          break;
+        default:
+          break;
+      }
+    }
+    return { id, content, stopReason, usage };
+  }
+}
+
+// src/core/skill.ts
+class Skill {
+  name;
+  description;
+  content;
+  constructor({
+    name,
+    description,
+    content
+  }) {
+    this.name = name;
+    this.description = description;
+    this.content = content;
+  }
+}
+
+// src/skills/codeSimplifier/SKILL.md
+var SKILL_default = `---
+name: code-simplifier
+description: Simplifies and refines recently-modified code for clarity, consistency, and naming without changing behaviour. Applies edits in place. Use when the user asks to simplify, tidy, refine, or clean up code they just wrote or changed \u2014 not when they want a review report or a whole-repo audit.
+---
+
+# Code simplifier
+
+Refine recently-modified code for clarity, consistency, and maintainability *without changing behaviour*. Apply edits in place.
+
+Out of scope: producing a severity-tiered review report, auditing a whole repo for ergonomics, refactors that change observable behaviour.
+
+## Scope
+
+Operate only on code the user just wrote or changed in this session, unless they explicitly point you at older code. Don't fish across the repo.
+
+If you're not sure which code is in scope, ask once before editing.
+
+## Preserve behaviour
+
+Non-negotiable. After any edit:
+
+- Public API shapes are unchanged.
+- Outputs, side effects, and error semantics are unchanged.
+- Tests that passed before still pass.
+
+If a simplification would alter behaviour \u2014 even marginally \u2014 surface it as a *suggestion* with the tradeoff stated. Do not apply.
+
+## What to simplify
+
+In rough order of payoff:
+
+1. **Reduce nesting.** Early returns, guard clauses, flat control flow.
+2. **Remove dead or redundant code.** Unreachable branches, duplicate logic, unused exports.
+3. **Inline single-use indirection.** A helper called once with no reuse value is just noise.
+4. **Improve naming.** Vague names (\`data\`, \`temp\`, \`handle\`) \u2192 concrete ones grounded in the domain.
+5. **Untangle ternaries.** Nested ternaries \u2192 \`if\`/\`else\` chains or named intermediate variables.
+6. **Drop redundant comments.** Anything that just restates the next line.
+7. **Match local style.** Mirror the conventions of the surrounding file before defaulting to "what I'd write."
+
+## What not to do
+
+- Don't extract abstractions to "future-proof". Three similar lines are fine.
+- Don't golf \u2014 fewer lines isn't the goal, fewer concepts is.
+- Don't rewrite paragraphs of working code to suit your taste.
+- Don't widen the scope to the rest of the file unless the user said so.
+
+## Output
+
+Apply edits with \`Edit\`. For each edit, state in one line *what* and *why* \u2014 e.g. "\`src/foo.ts:42\` \u2014 extracted guard clause, drops 2 levels of nesting."
+
+If you can't apply an edit (would change behaviour, or you're unsure), surface it as a one-line suggestion instead of applying.
+`;
+
+// src/skills/developerExperience/SKILL.md
+var SKILL_default2 = `---
+name: developer-experience
+description: Reviews a software surface \u2014 a whole repo, an SDK/API, a diff or PR, a single commit, a single file, or a design proposal \u2014 as a linter for developer experience (DX) and agent experience (AX). Surfaces papercuts: friction, inconsistent naming, unidiomatic REST, weak errors, untyped boundaries, and patterns that make the surface hard for LLM-driven agents to consume. Use when the user asks to audit DX, AX, ergonomics, or how a surface feels to use, at any scope.
+---
+
+# Developer experience
+
+Review a software surface as a *linter for developer experience*. Surface papercuts \u2014 friction (the user had to know something undocumented to succeed) and inconsistency (the same concept named, shaped, or behaved-with two different ways). Equally evaluates **agent experience** (AX): how easily an LLM-driven agent can use the surface.
+
+Out of scope: refactoring the code, writing user-facing docs.
+
+## Scope
+
+This skill adapts to the *surface area* under review. Decide it from what you were asked:
+
+- **Whole repo / SDK / API** \u2014 the full public surface.
+- **A diff or PR** \u2014 only the surface the change adds, removes, or alters, plus its immediate blast radius.
+- **A single commit** \u2014 the surface that commit touches.
+- **A single file or module** \u2014 the public surface that file exposes.
+- **A proposal / RFC / design doc** \u2014 the surface as *described*; there is no code to read yet.
+- Ambiguous \u2192 ask which.
+
+The dimensions, the citation rule, and the what-not-to-flag list below are identical at every scope. Only *what you read* and *how you bound the review* change.
+
+## How to make the review tractable
+
+Match the method to the scope. Three passes keep any scope from drowning:
+
+1. **Map the surface.** Enumerate the public surface only \u2014 skip internals.
+   - Repo / SDK / API: exported endpoints (router files, OpenAPI), exported symbols (\`index.ts\`, \`package.json#exports\`), error classes, the README quickstart.
+   - Diff / commit: only the public symbols the change adds, removes, or alters.
+   - File: the symbols that file exports.
+   - Proposal: the surface the document describes.
+2. **Sample.** For a large surface, pick 3\u20135 representative resources / endpoints / tools and review them deeply against the dimensions below. The goal is *patterns*, not coverage. For a diff-sized or single-file surface, review all of it.
+3. **Place each finding.** Ask: is this **local** (this one symbol) or **systemic** (a pattern across the surface, or drift the change introduces against an existing convention)? Systemic outranks local.
+
+Result: review cost is O(surface under review), not O(LOC).
+
+## The citation rule
+
+Every finding must cite either:
+
+- A public reference \u2014 Stripe error docs, Google AIP, Microsoft REST guidelines, JSON:API \xA7, Anthropic's "Writing tools for agents", RFC 9457, etc. *or*
+- The surface's own internal inconsistency \u2014 endpoint A does X, endpoint B does Y.
+
+If neither applies, drop it. "I would have\u2026" is not a citation. This is the single biggest guardrail against taste-creep.
+
+## DX dimensions
+
+Roughly in priority order. Lenses, not a checklist:
+
+1. **Consistency of shapes & naming** \u2014 case (snake vs camel), plurality, ID format, response envelope. Compounds across every endpoint.
+2. **Error design** \u2014 structured object with stable \`code\`, human \`message\`, \`documentation_url\`, optional \`param\` / \`pointer\`. No leaking stack traces.
+3. **Authentication & onboarding** \u2014 time-to-first-200, key creation friction, scopes, rotation.
+4. **Resource modeling** \u2014 nouns, plural collections, hierarchy depth \u2264 1, list vs item endpoints.
+5. **Pagination, filtering, sorting** \u2014 one mechanism repo-wide; cursors stable and opaque; documented defaults and caps.
+6. **Versioning & deprecation** \u2014 explicit policy; deprecation visible in *both* the response and the docs.
+7. **Idempotency & safe retries** \u2014 keys on writes, documented replay window, retriable-vs-not made explicit.
+8. **Type safety on the SDK boundary** \u2014 no \`any\`, generics that infer, discriminated result types, branded nominal IDs, no stringly-typed enums.
+9. **Docs you can copy-paste** \u2014 runnable examples, env-var conventions, every parameter documented incl. enum values.
+10. **Observability hooks** \u2014 request IDs in responses and errors, webhook signatures.
+11. **Defaults & footguns** \u2014 sane defaults, no silent truncation or coercion.
+12. **Long-running operations** \u2014 one documented pattern (operation polling, webhook, async job), not three.
+
+## AX dimensions
+
+Where DX and AX diverge. These are the concrete checks defensible today \u2014 skip speculation about "what agents would prefer".
+
+1. **Machine-readable spec exists and is current.** OpenAPI / TypeSpec / GraphQL SDL / Smithy committed; generated SDKs match.
+2. **Errors are programmatically branchable.** \`code\` is a stable enum, not free-text. \`is_retriable\` / \`retry_after\` present where meaningful.
+3. **Non-interactive auth path.** API key or client-credentials works headlessly \u2014 no mandatory browser, CAPTCHA, or MFA on the agent path.
+4. **Token-efficient responses.** Lists paginate. Field selection or \`expand\` supported. Default payload doesn't dump internal UUIDs and base64 blobs.
+5. **Self-contained tool/endpoint descriptions.** Every parameter described, enum values listed, "what happens when omitted" stated.
+6. **Predictable schemas.** Same request, same response shape. No flags that silently change return type.
+7. **Stable docs URL or \`llms.txt\`.** Deprecation flagged in the *spec*, not only in HTML.
+8. **Namespacing & discoverability.** Tools/endpoints grouped by resource with consistent prefixes.
+
+## What not to flag
+
+- Stylistic taste with no concrete cost ("would be more elegant as\u2026").
+- Linter / formatter territory (semicolons, import order, prettier output).
+- Performance speculation without a measurement.
+- Protocol religion (REST vs GraphQL vs gRPC).
+- Choices a framework forces.
+- Single-occurrence naming nits when the convention is otherwise consistent.
+- When the scope is a diff or commit: pre-existing papercuts outside the surface the change touches \u2014 note systemic drift the change *introduces*, not debt it merely sits next to.
+
+## Output
+
+Markdown, sections optional \u2014 omit any that's empty:
+
+\`\`\`
+## Papercuts (blocking)
+- <statement>. \`src/path.ts:42\` \u2014 <why it hurts, citing rule or surface inconsistency>
+
+## Worth addressing
+- ...
+
+## Nits / consistency drift
+- ...
+
+## Agent-experience notes
+- <AX-specific findings, separated because the fix audience may differ>
+\`\`\`
+
+End with one line \u2014 a verdict on the surface under review. One of: \`Idiomatic\`, \`Idiomatic with rough edges\`, \`Needs work\`, \`Hostile to agents\`. When reviewing a proposal, frame each finding against the surface it *would* create and phrase the verdict accordingly.
+
+No numeric scores. No praise section. Every finding cites a file/line (or, for a proposal, the section it refers to) or a public reference.
+`;
+
+// src/skills/docsUpdate/SKILL.md
+var SKILL_default3 = `---
+name: docs-update
+description: Keeps a repo's internal docs (AGENTS.md / CLAUDE.md, docs/**/*.md) in sync with a code change. Routes each fact to one canonical home, preserves the existing voice, and skips trivial changes. Use after a PR-sized change set when public API, commands, structure, or stack claims may have shifted.
+---
+
+# Docs update
+
+Keep a repo's *internal* docs (\`AGENTS.md\` / \`CLAUDE.md\`, \`docs/**/*.md\`) in sync with a code change. Surgical edits, one canonical home per fact, matched voice.
+
+Out of scope: \`README.md\`, public/user-facing docs sites (Mintlify, Docusaurus, API reference), changelogs, release notes.
+
+## When this runs
+
+After a PR-sized change set lands or is about to. Skip for:
+
+- Typo / formatting / comment-only changes.
+- Internal refactors with no change to public API, CLI, config, env vars, scripts, or directory layout.
+- Dependency bumps that don't change usage.
+- Test-only changes.
+
+If unsure whether a change is doc-worthy, default to *no edit*. Drift is cheaper than slop.
+
+## Inputs
+
+Read once, hold in memory:
+
+- The diff: \`git diff <base>..HEAD --name-only\` and \`git diff <base>..HEAD\` (or the staged diff if pre-commit).
+- The docs in scope: \`AGENTS.md\` / \`CLAUDE.md\` and \`docs/**/*.md\`. Skip \`README.md\`.
+
+Do not pre-read source files. Open them only to verify a specific claim.
+
+## Routing \u2014 one fact, one home
+
+| Fact type | Lives in |
+|---|---|
+| Build/test/lint commands, conventions, gotchas, project structure | \`AGENTS.md\` |
+| Multi-page how-to, architecture, ADRs | \`docs/<topic>.md\` |
+
+When a fact lands in the diff:
+
+1. Look for an existing doc that already covers the topic \u2014 edit there.
+2. If none, place it in the *narrowest* home: a bullet in \`AGENTS.md\` before a new \`docs/\` page.
+3. Never duplicate. If a fact must be referenced from multiple docs, write it once and link.
+
+## Staleness detection
+
+Cheap pass: scan each doc for code-shaped tokens, verify they still resolve.
+
+- Backticked commands \u2192 still in \`package.json\` scripts / \`Makefile\` / on \`PATH\`?
+- \`file:line\` and \`path/to/x\` references \u2192 file still exists, line still relevant?
+- Named exports, types, CLI flags, env vars, config keys \u2192 still present?
+- Stack / runtime / version claims \u2192 match \`package.json\`, lockfile, \`engines\`?
+- Module-tree descriptions \u2192 match the actual \`src/\` layout?
+
+Anything quoted in a doc that the diff invalidates is a *must-fix*. Add new facts only when the diff introduces something a reader would expect to find documented and currently can't.
+
+## Voice preservation
+
+Before editing a doc, sample its existing tone \u2014 sentence length, hedging, capitalization, list style. Match it. Edit with \`Edit\` (string replacement), not full rewrites; a one-line change should touch one line.
+
+Words to avoid introducing: *comprehensive*, *robust*, *seamlessly*, *leverage*, *in order to*, *cutting-edge*. If a phrase reads like marketing or like an LLM wrote it, rewrite it in the doc's own voice or leave it out.
+
+## AGENTS.md specifically
+
+- Keep under ~50 lines. If a topic outgrows that, move to \`docs/<topic>.md\` and link.
+- Prefer \`file:line\` references over inline code snippets \u2014 snippets rot.
+- Omit anything a linter or formatter already enforces.
+- No badges, no ToC, no "Why this project?".
+
+## Output
+
+For each proposed change, state:
+
+- The file.
+- A one-line reason tied to the diff (e.g. "renamed \`Tool.handler\` \u2192 \`Tool.execute\` (src/core.ts:100)").
+- The edit, applied via \`Edit\`.
+
+After applying edits, run the repo's check command (often \`bun run check\` or equivalent) to catch broken refs in fenced code blocks.
+
+If no edits are warranted, say so in one line and stop.
+`;
+
+// src/skills/prReview/SKILL.md
+var SKILL_default4 = `---
+name: pr-review
+description: Reviews a pull request or branch diff and produces a short, severity-tiered report (must-fix / should-consider / nits) with a final verdict. Use when the user asks to review a PR, review their branch, look at someone else's PR, or mentions a PR number / URL.
+---
+
+# PR review
+
+Review a pull request or branch diff for blocking issues before it merges. The output is a short, severity-tiered report \u2014 not a checklist run.
+
+## Scope
+
+Three sources. Pick by what the user said:
+
+- A PR number, PR URL, or \`#NNN\` \u2192 remote PR. Use \`gh pr view <id> --json title,body,baseRefName,headRefName,author\` for context and \`gh pr diff <id>\` for the patch.
+- "review my branch", "review this branch" \u2192 local diff. Base is \`git merge-base HEAD origin/<default-branch>\`. Use \`git diff <base>...HEAD\` for the patch and \`git log <base>..HEAD --oneline\` for intent.
+- Ambiguous \u2192 ask which one.
+
+Skip drafts, lockfiles, and generated files unless explicitly asked.
+
+## Context
+
+Load just enough to ground judgement:
+
+- Any \`AGENTS.md\` / \`CLAUDE.md\` in the changed files' directory ancestry. These are the source of truth for project conventions.
+- PR title + description, or branch commit messages \u2014 to know the *intent* before reading the patch.
+
+Do not pre-read the whole repo. Open files as questions arise during the scan.
+
+Do not run the project's lint, typecheck, or test commands. CI already runs them on the same diff, and their output is not more informative than the diff itself.
+
+## Reading the diff
+
+Three passes. Single-pass review misses things and over-flags.
+
+1. **Skim.** Summarise the change in one line. Decide if review is warranted. Drafts, pure renames, dep bumps without lockfile changes, mechanical refactors: say so and stop.
+2. **Scan.** Walk the diff hunk by hunk. Weigh each hunk against the dimensions below. Note *candidate* findings; do not yet decide what to report.
+3. **Validate.** For every candidate, ask: can I quote the rule it breaks, the input that makes it fail, or the convention in \`AGENTS.md\` it violates? If not, drop it. False positives erode trust faster than missed positives.
+
+## Dimensions
+
+In rough priority order \u2014 these are lenses, not a checklist:
+
+1. **Correctness** \u2014 logic, off-by-one, null/empty, error paths, async/race.
+2. **Security** \u2014 injection, authz, secrets, deserialization, data exposure. Diff-scoped only.
+3. **Blast radius / design fit** \u2014 does the change belong here? Does it cross boundaries it shouldn't?
+4. **Tests** \u2014 present where risk warrants, exercising behaviour not implementation.
+5. **Convention adherence** \u2014 what \`AGENTS.md\` and adjacent code say.
+6. **API & contract** \u2014 backward-compat, error semantics, public types.
+7. **Naming & readability** \u2014 only when genuinely confusing.
+
+## What not to flag
+
+These destroy signal-to-noise:
+
+- Pre-existing issues in unchanged code (diff-scoped only).
+- Style and formatting a linter catches.
+- "Could be more idiomatic" without a concrete reason.
+- Theoretical performance concerns without measurement.
+- Missing tests for trivial or mechanical changes.
+- Documentation for self-evident code.
+
+## Output
+
+Markdown. Lead with one line summarising the change (the same summary from the skim pass) \u2014 always, even when there are no findings. Then up to three sections, all optional \u2014 omit any that's empty:
+
+\`\`\`
+<one-line summary of the change>
+
+## Must fix
+- <statement>. \`path/to/file.ts:42\` \u2014 <suggested replacement *or* a question>
+
+## Should consider
+- ...
+
+## Nits
+- ...
+\`\`\`
+
+End with one line \u2014 a verdict. One of: \`Approve\`, \`Approve with must-fixes\`, \`Request changes\`.
+
+No praise section. No confidence scores. Include a committable suggestion only when it fully fixes the issue with no follow-up.
+
+## Posting (remote PRs only)
+
+If the user asks to post findings: submit the verdict with \`gh pr review\`, choosing the action that matches it \u2014 \`Approve\` \u2192 \`--approve\`, \`Request changes\` \u2192 \`--request-changes\`, \`Approve with must-fixes\` \u2192 \`--comment\` (advisory) or \`--request-changes\` (gating), caller's choice \u2014 and \`gh api\` for inline comments anchored to \`path\` + \`line\`. Never auto-post.
+`;
+
+// src/skills/publicDocs/SKILL.md
+var SKILL_default5 = `---
+name: public-docs
+description: Writes and maintains external, user-facing docs for an SDK / API / product, run from a docs repo with upstream source repos as context. Classifies each page as quickstart / concept / how-to / reference / recipe, prefers generated shape with hand-written meaning, and avoids duplication with the SDK README. Use when working in a docs repo (Mintlify, Docusaurus, or plain markdown) or when the user asks to write or refresh public/user-facing docs.
+---
+
+# Public docs
+
+Write and maintain external, user-facing docs for an SDK, API, or product. This skill runs from a docs repo and treats upstream code repos (SDK source, backend, OpenAPI spec) as context.
+
+Out of scope: the docs repo's own internal README / \`AGENTS.md\`, changelogs, marketing copy.
+
+## First, orient
+
+Three things to discover before writing anything:
+
+1. **Output format.** Inspect the repo root:
+   - \`docs.json\` / \`mint.json\` \u2192 Mintlify (MDX).
+   - \`docusaurus.config.*\` \u2192 Docusaurus (MDX).
+   - Otherwise \u2192 plain Markdown.
+2. **Upstream source.** Where does the truth live? Look for \`.upstream-refs.json\`, a \`package.json\` \`repository\` field, or a CONTRIBUTING note. If none, ask once and record the answer.
+3. **Existing pages on the same topic.** Grep the docs tree before drafting. Update > duplicate.
+
+## Doc types \u2014 classify before drafting
+
+Each page is *one* of these. Mixing modes is the most common cause of bad docs.
+
+| Type | Reader posture | Contains | Does not contain |
+|---|---|---|---|
+| Quickstart | Skim & copy | Prereqs, install, auth, one runnable request, expected response, next-step links | Concepts, full param tables, alternatives |
+| Concept | Sit & read | Mental model, terms defined once, "how it fits" | Code, step-by-step, exhaustive params |
+| How-to | Scan for step | Goal, prereqs, numbered steps, verification, troubleshooting | Theory, tangential alternatives |
+| Reference (API / SDK) | Ctrl-F | Signature or method+path, every param (type, required, default, description), example, response shapes, errors | Tutorials, opinion |
+| Recipe | Steal & adapt | Full runnable file, what to change | Production caveats stacked at the end |
+
+Heading is the question the reader asked, not the noun. "How to rotate keys", not "Key rotation".
+
+## Voice
+
+- Second person, active, present tense. *"Create a key"*, not *"A key is created"*.
+- One term per concept, used everywhere. Pick "API key" or "API token", not both.
+- Open with the verb. No "Welcome to\u2026", "We're excited to\u2026", "Simply\u2026", "Note that\u2026".
+- Banned adjectives: *powerful, robust, seamless, magical, blazing-fast, simply*. If a sentence reads like marketing, cut it.
+
+## Mintlify MDX components
+
+Use sparingly. Plain markdown beats a component that adds no information.
+
+| Component | Use for | Avoid for |
+|---|---|---|
+| \`<CodeGroup>\` | Same task in multiple languages | A single snippet |
+| \`<Steps>\` | Ordered, irreversible procedures | Tips, "best practices" |
+| \`<Tabs>\` | Same code across runtimes (Node / Deno / Bun) | Different concepts side-by-side |
+| \`<Cards>\` | Hub or landing pages | Mid-flow navigation |
+| \`<ParamField>\` / \`<ResponseField>\` | Reference param tables | Concept pages |
+| \`<Note>\` / \`<Warning>\` | Genuine constraint or footgun, at most one per page | Praise, sales tone, padding |
+| \`<Accordion>\` | Genuinely optional depth | Hiding required reading |
+
+## Generate the shape, hand-write the meaning
+
+| Surface | Approach |
+|---|---|
+| REST endpoints | Generate the reference from OpenAPI. Hand-write the intro paragraph and examples. |
+| TypeScript SDK | Generate signatures from \`tsc --declaration\` or TypeDoc. Hand-write usage and concept links. |
+| Webhooks, errors | Hand-write, cross-checked against a source-of-truth enum or schema. |
+| Quickstart, concept, how-to | Always hand-write. |
+
+Generated content with no prose around it reads like \`--help\`. Don't ship it.
+
+## Cross-links to upstream code
+
+- Default: link to the SDK's *own published docs page*, not its source.
+- When pointing at an implementation detail, link a permalink at a commit SHA \u2014 never \`main\`. \`main\` links rot silently.
+- Never paste upstream source into a docs page. Snapshot drift > linking cost.
+
+## Avoid duplication with the SDK README
+
+The README owns: *what is it*, one runnable example, link to the docs. Nothing else.
+
+The docs own: quickstart, concepts, references, how-tos.
+
+If a section appears in both, the docs are canonical and the README links to them. Propose collapsing duplicates when you find them.
+
+## Detecting staleness
+
+Cheap pass before writing:
+
+- For pages with \`<ParamField>\` / \`<ResponseField>\` / fenced code calling SDK symbols \u2192 fetch the upstream file at the latest tagged release and check the symbols still exist.
+- For OpenAPI-driven references \u2192 compare the spec hash in the docs repo to the upstream spec. If they diverge, the reference is stale.
+- Backticked commands and config keys \u2192 verify they still appear in the upstream README or source.
+
+Anything quoted in the docs that the upstream invalidates is a must-fix.
+
+## Output
+
+For each page touched:
+
+- State the doc type and whether it's a new page or an edit.
+- One-line reason tied to the upstream change (or to the user's request).
+- Apply via \`Edit\` for changes, \`Write\` for new pages.
+
+After edits, run the docs repo's check (\`mintlify dev\`, \`docusaurus build\`, or repo-specific) to catch broken MDX and link rot.
+`;
+
+// src/skills/index.ts
+function parseSkill(raw) {
+  const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(raw);
+  if (!match) {
+    throw new Error("Skill is missing YAML frontmatter.");
+  }
+  const [, frontmatter, body] = match;
+  if (frontmatter === undefined || body === undefined) {
+    throw new Error("Skill frontmatter could not be parsed.");
+  }
+  const fields = {};
+  for (const line of frontmatter.split(`
+`)) {
+    const kv = /^([A-Za-z][\w-]*):\s*(.+)$/.exec(line);
+    if (kv?.[1] && kv[2])
+      fields[kv[1]] = kv[2].trim();
+  }
+  const name = fields.name;
+  const description = fields.description;
+  if (!name)
+    throw new Error('Skill frontmatter is missing "name".');
+  if (!description)
+    throw new Error('Skill frontmatter is missing "description".');
+  return new Skill({ name, description, content: body.trimStart() });
+}
+var prReview = parseSkill(SKILL_default4);
+var docsUpdate = parseSkill(SKILL_default3);
+var publicDocs = parseSkill(SKILL_default5);
+var developerExperience = parseSkill(SKILL_default2);
+var codeSimplifier = parseSkill(SKILL_default);
+export {
+  publicDocs,
+  prReview,
+  docsUpdate,
+  developerExperience,
+  codeSimplifier
+};