toolfactory 0.1.1

package/src/surfaces/pypi.ts

@@ -0,0 +1,84 @@
+/**
+ * PyPI package: identity projected into pyproject.toml (merge; the author owns the rest),
+ * the console script for the CLI, and the MCP Registry ownership marker, which for PyPI is
+ * an `mcp-name:` line in the README the registry reads back off the published project page.
+ */
+import { cliEntryPoint, projectTable, pythonPackage } from "../bindings/python.js";
+import type { Surface } from "../model.js";
+import { registryName } from "./mcp-registry.js";
+import { compact, has } from "./shared.js";
+import { WEB_DIR } from "./web.js";
+
+export const README_PATH = "README.md";
+export const MCP_NAME_BEGIN = "<!-- tf:mcp-name -->";
+export const MCP_NAME_END = "<!-- /tf:mcp-name -->";
+
+export const surface: Surface = {
+  id: "pypi",
+  plan(project) {
+    if (project.tool.binding !== "python") {
+      throw new Error('Surface "pypi" requires the python binding.');
+    }
+    const authored = project.tool.identity === "pyproject.toml";
+    const registry = has(project, "mcp-registry");
+    const patch = {
+      project: compact({
+        ...(authored ? {} : projectTable(project)),
+        readme: registry ? README_PATH : undefined,
+        scripts: has(project, "cli")
+          ? { [project.identity.name]: cliEntryPoint(project) }
+          : undefined,
+      }),
+      // The kernel serves the built page from inside its own package, so the wheel has to
+      // carry it: `packages` only copies the package tree, `force-include` maps anything else.
+      ...(has(project, "web")
+        ? {
+            tool: {
+              hatch: {
+                build: {
+                  targets: {
+                    wheel: {
+                      "force-include": {
+                        [`${WEB_DIR}/dist`]: `${pythonPackage(project)}/${WEB_DIR}`,
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          }
+        : {}),
+    };
+    const files = [
+      {
+        kind: "merge" as const,
+        path: "pyproject.toml",
+        format: "toml" as const,
+        patch,
+        owned: ["project.scripts"],
+      },
+    ];
+    if (!registry) return files;
+    const marker = `\n<!-- mcp-name: ${registryName(project)} -->\n`;
+    return [
+      ...files,
+      {
+        kind: "region" as const,
+        path: README_PATH,
+        regions: [{ begin: MCP_NAME_BEGIN, end: MCP_NAME_END, content: marker }],
+        template: [
+          `# ${project.identity.name}`,
+          "",
+          project.identity.description ?? "",
+          "",
+          MCP_NAME_BEGIN,
+          MCP_NAME_END,
+          "",
+        ].join("\n"),
+      },
+    ];
+  },
+  validate(project) {
+    return [{ label: "uv build", command: "uv", args: ["build"], cwd: project.root }];
+  },
+};

package/src/surfaces/readme.ts

@@ -0,0 +1,218 @@
+/**
+ * Surface "readme": the `<!-- tf:install -->` region of `README.md`, always generated (like
+ * `workflows` and `agents`; never in `tool.json.surfaces`). One install line per selected
+ * distribution surface, in the exact shape that surface's own installer accepts, so the
+ * humans-and-agents-facing half of distribution cannot drift from the artifacts. The prose
+ * around the region — what the tool is, how to use it — is the author's, forever.
+ *
+ * Every line works from a plain checkout; the ones that need a GitHub repository (`npx skills
+ * add`, the Agent Skill badge, the marketplace and Hermes clone URLs) appear only once the
+ * identity file carries one, so a tool built without GitHub still gets an accurate section.
+ *
+ * When `mcp` is selected alongside a package registry, the MCP line also carries the two
+ * first-party one-click badges (VS Code's `vscode.dev/redirect/mcp/install`, Cursor's
+ * `cursor.com/en/install-mcp`), both computed from the exact same `{command, args, env}` launch
+ * the plain-text line renders — a badge can never point somewhere the text line does not.
+ */
+import { githubSlug } from "../hosts/github.js";
+import { projectName } from "../identity/name.js";
+import type { Project, Surface } from "../model.js";
+import { HOST_DIR as BROWSER_HOST_DIR, zipName } from "./browser-extension.js";
+import { HOST_DIR as DSH_HOST_DIR, dshTarball } from "./dsh.js";
+import { pluginDir as hermesPluginDir } from "./hermes-native.js";
+import { HOST_DIR as OPENCLAW_HOST_DIR } from "./openclaw-native.js";
+import { envName, has, npmName, pypiName, requiredConfig } from "./shared.js";
+
+export const README_PATH = "README.md";
+export const INSTALL_BEGIN = "<!-- tf:install -->";
+export const INSTALL_END = "<!-- /tf:install -->";
+
+/** A stable label for repositories that ship an Agent Skill; unlike skills.sh's live count badge,
+ * it does not depend on a separate registry index. */
+function skillBadge(slug: string): string {
+  return `[![Agent Skill](https://img.shields.io/badge/Agent_Skill-available-5B5BD6)](https://github.com/${slug})`;
+}
+
+/**
+ * The kernel MCP server's published launch, unpinned — `{command, args}`, plus an `env` map of
+ * blank placeholders for whatever config the tool requires. The one source both `mcpCommand`
+ * (the plain-text line) and the VS Code / Cursor install badges below encode: a badge can never
+ * name a launch the text line does not.
+ */
+function launchConfig(project: Project): {
+  command: string;
+  args: string[];
+  env?: Record<string, string>;
+} {
+  const { command, args } =
+    project.tool.binding === "python"
+      ? (() => {
+          const pypi = pypiName(project);
+          // `uvx <pkg>` runs the command of the same name; a dotted tool name renames the package.
+          return pypi === project.identity.name
+            ? { command: "uvx", args: [pypi, "mcp"] }
+            : { command: "uvx", args: ["--from", pypi, project.identity.name, "mcp"] };
+        })()
+      : { command: "npx", args: ["-y", npmName(project), "mcp"] };
+  const required = requiredConfig(project);
+  return required.length
+    ? { command, args, env: Object.fromEntries(required.map((key) => [envName(key), ""])) }
+    : { command, args };
+}
+
+function mcpCommand(project: Project): string {
+  const { command, args } = launchConfig(project);
+  return [command, ...args].join(" ");
+}
+
+/** github.com/github/github-mcp-server's README badge, verbatim shields.io style. */
+function vscodeBadge(project: Project): string {
+  const config = encodeURIComponent(JSON.stringify(launchConfig(project)));
+  const url = `https://vscode.dev/redirect/mcp/install?name=${encodeURIComponent(project.identity.name)}&config=${config}`;
+  return `[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](${url})`;
+}
+
+/** cursor.com/docs/mcp/install-links's own badge SVG and `en/install-mcp` redirect. */
+function cursorBadge(project: Project): string {
+  const config = Buffer.from(JSON.stringify(launchConfig(project))).toString("base64");
+  const url = `https://cursor.com/en/install-mcp?name=${encodeURIComponent(project.identity.name)}&config=${config}`;
+  return `[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](${url})`;
+}
+
+function installLines(project: Project): string[] {
+  const { identity } = project;
+  const slug = githubSlug(identity.repository);
+  const lines: string[] = [];
+  if (has(project, "skill") && slug) {
+    lines.push(`- **Agent Skill** — \`npx skills add ${slug}\``);
+  }
+  if (has(project, "mcp")) {
+    // The one-click badges need a published package to point at: they read the same launch
+    // config the text line does, so they only appear once there is somewhere to `npx`/`uvx` from.
+    const badges =
+      has(project, "npm") || has(project, "pypi")
+        ? ` ${vscodeBadge(project)} ${cursorBadge(project)}`
+        : "";
+    lines.push(`- **MCP server** — \`${mcpCommand(project)}\`${badges}`);
+  }
+  if (has(project, "mcpb")) {
+    lines.push(
+      `- **Claude Desktop extension** — download \`${identity.name}.mcpb\` from the GitHub Release and double-click to install`,
+    );
+  }
+  if (has(project, "claude")) {
+    // The repository is its own marketplace (`.claude-plugin/marketplace.json`); Copilot CLI
+    // reads the same file with the same command.
+    lines.push(
+      `- **Claude Code plugin** — \`claude plugin marketplace add ${slug ?? "."}\`, then \`claude plugin install ${identity.name}@${identity.name}\``,
+    );
+  }
+  if (has(project, "codex")) {
+    // `.agents/plugins/marketplace.json` lists the repository's own plugin (`codex.ts`).
+    lines.push(
+      `- **Codex plugin** — \`codex plugin marketplace add ${slug ?? "."}\`, then \`codex plugin add ${identity.name}@${identity.name}\``,
+    );
+  }
+  if (has(project, "gemini")) {
+    lines.push(
+      slug
+        ? `- **Gemini CLI extension** — \`gemini extensions install https://github.com/${slug}\``
+        : "- **Gemini CLI extension** — `gemini extensions link .` from a checkout",
+    );
+  }
+  if (has(project, "openclaw-native")) {
+    const clawhub = has(project, "clawhub")
+      ? `; published: \`openclaw plugins install clawhub:${projectName.openclawPackage(identity.name)}\``
+      : "";
+    lines.push(
+      `- **OpenClaw plugin** — \`openclaw plugins install --link ${OPENCLAW_HOST_DIR}\` from a checkout${clawhub}`,
+    );
+  }
+  if (has(project, "hermes-native")) {
+    const source = slug ? `https://github.com/${slug}` : "file://$PWD";
+    lines.push(
+      `- **Hermes plugin** — \`hermes plugins install ${source}#${hermesPluginDir(project)}\``,
+    );
+  }
+  if (has(project, "dsh")) {
+    // `dsh plugin` is a pnpm forwarder: it installs a path, a tarball or a registry spec.
+    lines.push(
+      `- **DSH plugin** (experimental) — \`dsh plugin --profile <profile> add ./${DSH_HOST_DIR}\` from a checkout, or the release tarball \`${dshTarball(project)}\``,
+    );
+  }
+  if (has(project, "browser-extension")) {
+    // Three channels, in the order a reader needs them: build-and-load from a checkout, the
+    // release assets (only Mozilla's signed xpi is a real self-hosted install — Chrome drops
+    // side-loaded unpacked extensions), the store listings. Pairing is the last step of each.
+    const zips = (["chrome", "firefox", "edge"] as const).map(
+      (browser) => `\`${zipName(project, browser)}\``,
+    );
+    lines.push(
+      [
+        `- **Browser extension** — from a checkout: \`npm --prefix ${BROWSER_HOST_DIR} install && npm --prefix ${BROWSER_HOST_DIR} exec --no -- wxt build\`,`,
+        `  then \`chrome://extensions\` → developer mode → Load unpacked → \`${BROWSER_HOST_DIR}/.output/chrome-mv3\``,
+        `  (Firefox: \`npm --prefix ${BROWSER_HOST_DIR} exec --no -- web-ext run\`). Each GitHub Release attaches the`,
+        `  store uploads ${zips.join(", ")}, and the Mozilla-signed \`.xpi\`,`,
+        "  which is the only download-and-install channel now that Chrome no longer keeps side-loaded unpacked",
+        "  extensions; the Chrome Web Store, Firefox Add-ons and Edge Add-ons listings appear once the release's",
+        `  submit step has each store's credentials. Then pair it: \`${mcpCommand(project)} --http --pair\``,
+        "  prints the `<url>#<token>` the extension's options page accepts.",
+      ].join("\n"),
+    );
+  }
+  if (has(project, "web")) {
+    // Not an install: the one command that puts the page in front of a human, from wherever the
+    // tool already is. The same listener answers `/mcp`, so the page needs nothing else running.
+    lines.push(
+      `- **Web app** — \`${mcpCommand(project)} --http --open\` serves the operations page beside the`,
+      "  MCP endpoint on one port and opens it; over MCP or a skill, the `web` operation does the same and",
+      "  returns the URL.",
+    );
+  }
+  if (has(project, "npm")) lines.push(`- **npm package** — \`npm install ${npmName(project)}\``);
+  if (has(project, "pypi")) lines.push(`- **PyPI package** — \`uv add ${pypiName(project)}\``);
+  return lines;
+}
+
+/** The content of the generated region — everything between the markers, not the markers. */
+export function installContent(project: Project): string {
+  const slug = githubSlug(project.identity.repository);
+  const badge = has(project, "skill") && slug ? [skillBadge(slug), ""] : [];
+  const lines = installLines(project);
+  return `${[
+    "",
+    "## Install",
+    "",
+    ...badge,
+    ...(lines.length
+      ? lines
+      : ["_No installable surface is selected: this repository ships source only._"]),
+    "",
+  ].join("\n")}\n`;
+}
+
+function template(project: Project): string {
+  return [
+    `# ${project.identity.name}`,
+    "",
+    project.identity.description ?? "One paragraph: what this tool does, and for whom.",
+    "",
+    INSTALL_BEGIN,
+    INSTALL_END,
+    "",
+  ].join("\n");
+}
+
+export const surface: Surface = {
+  id: "readme",
+  plan(project) {
+    return [
+      {
+        kind: "region",
+        path: README_PATH,
+        regions: [{ begin: INSTALL_BEGIN, end: INSTALL_END, content: installContent(project) }],
+        template: template(project),
+      },
+    ];
+  },
+};

package/src/surfaces/registry.ts

@@ -0,0 +1,79 @@
+import type { Surface, SurfaceId } from "../model.js";
+import { surface as agentPlugins } from "./agent-plugins.js";
+import { surface as agents } from "./agents.js";
+import { surface as browserExtension } from "./browser-extension.js";
+import { surface as claude } from "./claude.js";
+import { surface as codex } from "./codex.js";
+import { surface as cursor } from "./cursor.js";
+import { surface as dsh } from "./dsh.js";
+import { clawhub } from "./external.js";
+import { surface as gemini } from "./gemini.js";
+import { surface as hermesNative } from "./hermes-native.js";
+import { cli, mcp } from "./kernel.js";
+import { surface as mcpRegistry } from "./mcp-registry.js";
+import { surface as mcpb } from "./mcpb.js";
+import { surface as npm } from "./npm.js";
+import { surface as openclawNative } from "./openclaw-native.js";
+import { surface as pypi } from "./pypi.js";
+import { surface as readme } from "./readme.js";
+import { surface as skill } from "./skill.js";
+import { surface as web } from "./web.js";
+import { surface as workflows } from "./workflows.js";
+
+const registry: Partial<Record<SurfaceId, Surface>> = {
+  "agent-plugins": agentPlugins,
+  agents,
+  "browser-extension": { ...browserExtension, requires: ["mcp"] },
+  claude,
+  codex,
+  // Declared dependencies (§3): these projectors point at a file another surface writes, so a
+  // selection without it would ship an artifact referencing nothing. Refused at plan time.
+  cursor: { ...cursor, requires: ["agent-plugins"] },
+  clawhub,
+  // Reaches the kernel only through DSH's own MCP client, so the bundle is inert without it.
+  dsh: { ...dsh, requires: ["mcp"] },
+  // The manifest's only payload is the kernel's launch row: an extension without it is a
+  // context file and nothing else.
+  gemini: { ...gemini, requires: ["mcp"] },
+  cli,
+  mcp,
+  "mcp-registry": mcpRegistry,
+  // The bundle root is the npm tarball with its production dependencies installed into it, and
+  // its one row launches the kernel MCP server: without either surface there is nothing to pack.
+  mcpb: { ...mcpb, requires: ["mcp", "npm"] },
+  npm,
+  skill,
+  "hermes-native": hermesNative,
+  "openclaw-native": openclawNative,
+  pypi,
+  readme,
+  web: { ...web, requires: ["mcp"] },
+  workflows,
+};
+
+export function registerSurface(surface: Surface): void {
+  registry[surface.id] = surface;
+}
+
+export function getSurface(id: SurfaceId): Surface {
+  const surface = registry[id];
+  if (!surface) throw new Error(`Surface "${id}" is not implemented in this toolfactory version.`);
+  return surface;
+}
+
+export function selectedSurfaces(ids: readonly SurfaceId[]): Surface[] {
+  return ids.map(getSurface);
+}
+
+/** A selection is valid only when every surface's declared dependencies are selected too. */
+export function assertSurfaceRequirements(ids: readonly SurfaceId[]): void {
+  const selected = new Set(ids);
+  for (const id of ids) {
+    for (const required of getSurface(id).requires ?? []) {
+      if (selected.has(required)) continue;
+      throw new Error(
+        `Surface "${id}" requires surface "${required}", which is not selected (surfaces: ${ids.join(", ")}). Select "${required}" or drop "${id}".`,
+      );
+    }
+  }
+}

package/src/surfaces/shared.ts

@@ -0,0 +1,140 @@
+/** Helpers shared by surface projectors. Pure. */
+import { projectName } from "../identity/name.js";
+import { type Operation, PORTABLE_CAPABILITIES, type Project, type Verdict } from "../model.js";
+import { defaultVerdict } from "../report/coverage.js";
+
+export const TOOLFACTORY_DIR = "dev.toolfactory";
+
+export function json(value: unknown): string {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+/** Drop undefined values so projections never emit `"key": undefined`. */
+export function compact<T extends Record<string, unknown>>(record: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(record).filter(([, value]) => value !== undefined),
+  ) as Partial<T>;
+}
+
+export function has(project: Project, surface: string): boolean {
+  return (project.tool.surfaces as string[]).includes(surface);
+}
+
+export function npmName(project: Project): string {
+  return projectName.npm(project.identity.name, project.tool.npm?.scope);
+}
+
+export function pypiName(project: Project): string {
+  return projectName.pypi(project.identity.name);
+}
+
+/** The launch command for the kernel MCP server as an installed package or a committed build. */
+export function kernelLaunch(
+  project: Project,
+  placeholderRoot: string,
+): { command: string; args: string[] } {
+  const { binding, bundle } = project.tool;
+  const version = project.identity.version ?? "latest";
+  if (bundle.runtime === "bundled") {
+    return binding === "python"
+      ? { command: "python3", args: [`${placeholderRoot}/bin/mcp.py`] }
+      : { command: "node", args: [`${placeholderRoot}/bin/mcp.js`] };
+  }
+  return binding === "python"
+    ? {
+        command: "uvx",
+        args: ["--from", `${pypiName(project)}==${version}`, project.identity.name, "mcp"],
+      }
+    : { command: "npx", args: ["-y", `${npmName(project)}@${version}`, "mcp"] };
+}
+
+/** Verdict for surfaces that only carry MCP tool calls: no host capabilities at all. */
+export function mcpVerdict(operation: Operation): Verdict {
+  const verdict = defaultVerdict(operation);
+  return verdict.kind === "excluded"
+    ? { kind: "excluded", reason: "excluded:mcp-no-host-capabilities" }
+    : verdict;
+}
+
+/** Verdict for skills hosts: non-portable operations are bridged by the agent driving the host's own tools. */
+/** A CLI has a human at the terminal, so user-input is native there; other host capabilities are not. */
+export function cliVerdict(operation: Operation): Verdict {
+  const portable = operation.requires.every(
+    (capability) => PORTABLE_CAPABILITIES.has(capability) || capability === "user-input",
+  );
+  return portable
+    ? { kind: "native" }
+    : { kind: "excluded", reason: "excluded:cli-no-host-capabilities" };
+}
+
+/** A skill never executes: the agent drives the CLI or MCP server, so everything it can reach is bridged. */
+export function skillVerdict(operation: Operation): Verdict {
+  if (operation.requires.includes("channel"))
+    return { kind: "excluded", reason: "excluded:no-channel-bridge" };
+  return { kind: "bridged", reason: "bridged:agent-mediated" };
+}
+
+export function configProperties(project: Project): Record<string, Record<string, unknown>> {
+  const properties = project.tool.config?.properties;
+  return properties && typeof properties === "object"
+    ? (properties as Record<string, Record<string, unknown>>)
+    : {};
+}
+
+export function isSensitive(property: Record<string, unknown>): boolean {
+  const meta = property["x-toolfactory"] as Record<string, unknown> | undefined;
+  return meta?.sensitive === true;
+}
+
+export function requiredConfig(project: Project): string[] {
+  const required = project.tool.config?.required;
+  return Array.isArray(required) ? (required as string[]) : [];
+}
+
+/** The environment variable a config key is read from, on every surface and in every environment. */
+export function envName(key: string): string {
+  return key.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+}
+
+/**
+ * Environment variable a host-native shim reads to find the tool's checkout when the host
+ * copied the plugin elsewhere (Hermes' doctor, OpenClaw's extensions directory).
+ */
+export function rootEnvName(project: Project): string {
+  return `${project.identity.name.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_ROOT`;
+}
+
+/**
+ * The environment variable a host passes the tool's per-instance data directory
+ * (caches, session state) through, on every surface. The kernel falls back to an
+ * XDG-style default when it is unset.
+ */
+export function dataDirEnvName(project: Project): string {
+  return `${project.identity.name.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_DATA_DIR`;
+}
+
+/**
+ * The credentials a live run needs: every config key that is both `required` and sensitive.
+ * A tool with none has nothing to gate a live tier on, so no live test and no `live` CI job.
+ */
+export function liveCredentials(project: Project): string[] {
+  const properties = configProperties(project);
+  const required = new Set(requiredConfig(project));
+  return Object.keys(properties).filter(
+    (key) => required.has(key) && isSensitive(properties[key] as Record<string, unknown>),
+  );
+}
+
+/**
+ * The operation the generated example test calls: the first one with arguments in
+ * `tool.json` `tests.examples`, else the first operation with no arguments.
+ */
+export function liveExample(
+  project: Project,
+): { name: string; args: Record<string, unknown> } | undefined {
+  const examples = project.tool.tests.examples;
+  const withExample = project.operations.find((operation) => examples[operation.name]);
+  const operation = withExample ?? project.operations[0];
+  if (!operation) return undefined;
+  return { name: operation.name, args: examples[operation.name] ?? {} };
+}

package/src/surfaces/skill.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from "vitest";
+import { parse as parseYaml } from "yaml";
+import type { Operation, Project } from "../model.js";
+import { frontmatter, renderOperations, skillPath, surface } from "./skill.js";
+
+const echo: Operation = {
+  name: "echo",
+  description: "Return the text you pass in.",
+  inputSchema: {
+    type: "object",
+    properties: { text: { type: "string" } },
+    required: ["text"],
+  },
+  requires: [],
+};
+const screenshot: Operation = {
+  name: "screenshot",
+  description: "Capture the current page.",
+  inputSchema: { type: "object", properties: {} },
+  requires: ["browser"],
+};
+const notify: Operation = {
+  name: "notify",
+  description: "Post a message into the live conversation.",
+  inputSchema: { type: "object", properties: {} },
+  requires: ["channel"],
+};
+
+function project(overrides: Partial<Project> = {}): Project {
+  return {
+    root: "/repo",
+    tool: {
+      schemaVersion: 1,
+      identity: "package.json",
+      binding: "typescript",
+      surfaces: ["skill", "cli", "mcp"],
+      bundle: { runtime: "package" },
+      tests: { examples: {} },
+    },
+    identity: { name: "hello", version: "1.0.0", description: "Say hello", license: "MIT" },
+    identityExtra: {},
+    operations: [echo, screenshot, notify],
+    toolfactoryVersion: "0.1.0",
+    ...overrides,
+  };
+}
+
+describe("skill surface", () => {
+  it("names the file after the tool and links it into the .agents canon", () => {
+    const target = project();
+    expect(skillPath(target)).toBe("skills/hello/SKILL.md");
+    expect(surface.plan(target)).toMatchObject([
+      { kind: "region", path: "skills/hello/SKILL.md" },
+      { kind: "file", path: ".agents/skills/hello", content: "../../skills/hello", symlink: true },
+    ]);
+  });
+
+  it("frontmatter carries the 6 spec fields, falling back to a description", () => {
+    const document = parseYaml(frontmatter(project()));
+    expect(document).toEqual({ name: "hello", description: "Say hello", license: "MIT" });
+
+    const noDescription = parseYaml(
+      frontmatter(project({ identity: { name: "hello", description: undefined } })),
+    );
+    expect(noDescription.description).toBe("Use the hello tool.");
+  });
+
+  it("the operations block includes a portable op's CLI/MCP invocation and a bridged op's text, and omits an excluded op", () => {
+    const body = renderOperations(project());
+
+    expect(body).toContain("### echo");
+    expect(body).toContain("`hello echo --json '<arguments>'` prints a JSON result.");
+    expect(body).toContain("MCP tool `echo` on server `hello`");
+    expect(body).toContain("Arguments: `text`.");
+
+    expect(body).toContain("### screenshot");
+    expect(body).toContain(
+      "This operation needs browser: drive this host's own browser tools and pass what they return as arguments.",
+    );
+
+    expect(body).not.toContain("### notify");
+  });
+
+  it("leaves the operations region empty for an instruction-only skill", () => {
+    const target = project({
+      tool: { ...project().tool, runtime: "none", surfaces: ["skill", "codex"] },
+      operations: [],
+    });
+    expect(renderOperations(target)).toBe("");
+  });
+
+  it("validate runs the upstream agentskills validator against skills/<name>", () => {
+    const commands = surface.validate?.(project()) ?? [];
+    expect(commands).toEqual([
+      {
+        label: "agentskills validate",
+        command: "uvx",
+        args: ["--from", "skills-ref", "agentskills", "validate", "skills/hello"],
+        cwd: "/repo",
+      },
+    ]);
+  });
+});