@stigmer/mcp-server 3.0.8-dev.20260612122433

package/src/domains/resourceuri.test.ts

@@ -0,0 +1,97 @@
+// Unit tests for stigmer:// resource URI parsing and construction.
+// Asserts parity with the Go server's behavior (scheme check, segment counts,
+// version handling, and the kind→authority round-trip).
+
+import { describe, expect, it } from "vitest";
+
+import {
+  buildResourceURI,
+  kindToAuthority,
+  parseResourceURI,
+  parseVersionedResourceURI,
+} from "./resourceuri";
+
+describe("parseResourceURI", () => {
+  it("extracts org and slug from a two-segment URI", () => {
+    expect(parseResourceURI("stigmer://agents/acme/code-reviewer")).toEqual({
+      org: "acme",
+      slug: "code-reviewer",
+    });
+  });
+
+  it("ignores the authority (kind) segment", () => {
+    // The authority differs but the org/slug are taken from the path only.
+    expect(parseResourceURI("stigmer://mcp-servers/acme/github")).toEqual({
+      org: "acme",
+      slug: "github",
+    });
+  });
+
+  it("rejects a non-stigmer scheme", () => {
+    expect(() => parseResourceURI("https://agents/acme/code-reviewer")).toThrow(/expected "stigmer"/);
+  });
+
+  it("rejects the wrong number of segments", () => {
+    expect(() => parseResourceURI("stigmer://agents/acme")).toThrow(/got 1/);
+    expect(() => parseResourceURI("stigmer://agents/acme/code-reviewer/v1")).toThrow(/got 3/);
+  });
+
+  it("rejects a malformed URI", () => {
+    expect(() => parseResourceURI("not a uri")).toThrow(/malformed resource URI/);
+  });
+});
+
+describe("parseVersionedResourceURI", () => {
+  it("treats two segments as latest (empty version)", () => {
+    expect(parseVersionedResourceURI("stigmer://skills/acme/my-skill")).toEqual({
+      org: "acme",
+      slug: "my-skill",
+      version: "",
+    });
+  });
+
+  it("extracts an explicit version from three segments", () => {
+    expect(parseVersionedResourceURI("stigmer://skills/acme/my-skill/v1.2.0")).toEqual({
+      org: "acme",
+      slug: "my-skill",
+      version: "v1.2.0",
+    });
+  });
+
+  it("rejects more than three segments", () => {
+    expect(() => parseVersionedResourceURI("stigmer://skills/acme/my-skill/v1/extra")).toThrow(
+      /got 4/,
+    );
+  });
+
+  it("rejects a single segment", () => {
+    expect(() => parseVersionedResourceURI("stigmer://skills/acme")).toThrow(/got 1/);
+  });
+});
+
+describe("buildResourceURI", () => {
+  it("builds a URI for every templated kind", () => {
+    expect(buildResourceURI("agent", "acme", "a")).toBe("stigmer://agents/acme/a");
+    expect(buildResourceURI("mcp_server", "acme", "m")).toBe("stigmer://mcp-servers/acme/m");
+    expect(buildResourceURI("skill", "acme", "s")).toBe("stigmer://skills/acme/s");
+    expect(buildResourceURI("workflow", "acme", "w")).toBe("stigmer://workflows/acme/w");
+  });
+
+  it("round-trips with parseResourceURI", () => {
+    const uri = buildResourceURI("agent", "acme", "code-reviewer");
+    expect(parseResourceURI(uri)).toEqual({ org: "acme", slug: "code-reviewer" });
+  });
+
+  it("returns empty string for an unknown kind", () => {
+    expect(buildResourceURI("organization", "acme", "x")).toBe("");
+  });
+
+  it("returns empty string when org or slug is empty", () => {
+    expect(buildResourceURI("agent", "", "x")).toBe("");
+    expect(buildResourceURI("agent", "acme", "")).toBe("");
+  });
+
+  it("covers exactly the four templated kinds", () => {
+    expect(Object.keys(kindToAuthority).sort()).toEqual(["agent", "mcp_server", "skill", "workflow"]);
+  });
+});

package/src/domains/resourceuri.ts

@@ -0,0 +1,124 @@
+// Parsing and construction of stigmer:// resource URIs.
+// Go parity: mcp-server/internal/domains/resourceuri.go.
+//
+// A resource URI has the form stigmer://{authority}/{org}/{slug}[/{version}].
+// The authority (e.g. "agents") is the URL host and encodes the kind; org/slug
+// (and optional version) are the path segments. Parsing deliberately validates
+// only the scheme and the path-segment count/shape — the authority is not
+// checked here, exactly as the Go server behaves.
+
+/** The org and slug extracted from a two-segment resource URI. */
+export interface ResourceRef {
+  readonly org: string;
+  readonly slug: string;
+}
+
+/** A resource ref that may also carry an explicit version ("" means latest). */
+export interface VersionedResourceRef extends ResourceRef {
+  readonly version: string;
+}
+
+/**
+ * Extract org and slug from a stigmer://{authority}/{org}/{slug} URI.
+ * Throws when the scheme is not "stigmer" or the path is not exactly two
+ * non-empty segments.
+ */
+export function parseResourceURI(uri: string): ResourceRef {
+  const segments = pathSegments(uri);
+  if (segments.length !== 2) {
+    throw new Error(
+      `expected URI path with 2 segments (org/slug), got ${segments.length} in "${uri}"`,
+    );
+  }
+  const org = segments[0] ?? "";
+  const slug = segments[1] ?? "";
+  if (org === "" || slug === "") {
+    throw new Error(`org and slug must be non-empty in "${uri}"`);
+  }
+  return { org, slug };
+}
+
+/**
+ * Extract org, slug, and optional version from a resource URI. Two path
+ * segments yield version "" (latest); three yield an explicit, non-empty
+ * version. Any other shape throws.
+ */
+export function parseVersionedResourceURI(uri: string): VersionedResourceRef {
+  const segments = pathSegments(uri);
+
+  let org = "";
+  let slug = "";
+  let version = "";
+  switch (segments.length) {
+    case 2:
+      org = segments[0] ?? "";
+      slug = segments[1] ?? "";
+      break;
+    case 3:
+      org = segments[0] ?? "";
+      slug = segments[1] ?? "";
+      version = segments[2] ?? "";
+      if (version === "") {
+        throw new Error(`version segment must be non-empty in "${uri}"`);
+      }
+      break;
+    default:
+      throw new Error(
+        `expected URI path with 2 or 3 segments (org/slug[/version]), got ${segments.length} in "${uri}"`,
+      );
+  }
+
+  if (org === "" || slug === "") {
+    throw new Error(`org and slug must be non-empty in "${uri}"`);
+  }
+  return { org, slug, version };
+}
+
+/**
+ * Map a singular kind name (as it appears in the ApiResourceKind proto enum) to
+ * the plural authority used in stigmer:// URIs. Only kinds that have a
+ * registered MCP resource template appear here.
+ */
+export const kindToAuthority: Readonly<Record<string, string>> = {
+  agent: "agents",
+  mcp_server: "mcp-servers",
+  skill: "skills",
+  workflow: "workflows",
+};
+
+/**
+ * Construct a stigmer:// URI from a kind, org, and slug — the inverse of
+ * {@link parseResourceURI}. Returns "" when the kind has no registered template
+ * or org/slug are empty, mirroring the Go server's enrichment fallback.
+ */
+export function buildResourceURI(kind: string, org: string, slug: string): string {
+  const authority = kindToAuthority[kind];
+  if (authority === undefined || org === "" || slug === "") {
+    return "";
+  }
+  return `stigmer://${authority}/${org}/${slug}`;
+}
+
+/**
+ * Parse the URI, assert the scheme, and return its path split into segments.
+ * The double-slash authority (the kind) is intentionally discarded; only the
+ * path carries org/slug[/version]. Interior empty segments are preserved so the
+ * count matches Go's strings.Split semantics.
+ */
+function pathSegments(uri: string): string[] {
+  let parsed: URL;
+  try {
+    parsed = new URL(uri);
+  } catch (err) {
+    throw new Error(`malformed resource URI "${uri}": ${err instanceof Error ? err.message : err}`);
+  }
+
+  if (parsed.protocol !== "stigmer:") {
+    throw new Error(
+      `unexpected URI scheme "${parsed.protocol.replace(/:$/, "")}", expected "stigmer"`,
+    );
+  }
+
+  const trimmed = parsed.pathname.replace(/^\/+/, "").replace(/\/+$/, "");
+  return trimmed === "" ? [] : trimmed.split("/");
+}

package/src/domains/rpcerr.test.ts

@@ -0,0 +1,62 @@
+import { Code, ConnectError } from "@connectrpc/connect";
+import { beforeAll, describe, expect, it } from "vitest";
+
+import { configureLogger } from "../logger";
+import { rpcError } from "./rpcerr";
+
+beforeAll(() => configureLogger({ level: "error", format: "text" }));
+
+const resource = 'agent "code-reviewer" in org "stigmer"';
+
+describe("rpcError", () => {
+  it("maps NotFound to a slug-guidance message", () => {
+    expect(rpcError(new ConnectError("missing", Code.NotFound), resource).message).toBe(
+      'agent "code-reviewer" in org "stigmer" not found. Verify the org and slug are correct.',
+    );
+  });
+
+  it("maps PermissionDenied to an API-key-permissions message", () => {
+    expect(rpcError(new ConnectError("nope", Code.PermissionDenied), resource).message).toBe(
+      'Permission denied for agent "code-reviewer" in org "stigmer". Check your API key permissions.',
+    );
+  });
+
+  it("maps Unauthenticated", () => {
+    expect(rpcError(new ConnectError("bad token", Code.Unauthenticated), resource).message).toBe(
+      "Authentication failed. Check your API key.",
+    );
+  });
+
+  it("maps Unavailable", () => {
+    expect(rpcError(new ConnectError("down", Code.Unavailable), resource).message).toBe(
+      "Stigmer server is unavailable. Ensure it is running and reachable.",
+    );
+  });
+
+  it("maps DeadlineExceeded", () => {
+    expect(rpcError(new ConnectError("slow", Code.DeadlineExceeded), resource).message).toBe(
+      "Request timed out contacting stigmer-server.",
+    );
+  });
+
+  it("passes through the raw message for InvalidArgument", () => {
+    expect(rpcError(new ConnectError("field x is required", Code.InvalidArgument), resource).message).toBe(
+      "field x is required",
+    );
+  });
+
+  it("wraps non-gRPC/unknown errors", () => {
+    expect(rpcError(new Error("boom"), resource).message).toBe("unexpected error: boom");
+  });
+
+  it("maps every gRPC code to a non-empty message without throwing", () => {
+    // Completeness guard: the default branch must catch any code the explicit
+    // switch does not handle, so no gRPC status can ever surface a blank or
+    // thrown error to the client.
+    const codes = Object.values(Code).filter((c): c is Code => typeof c === "number");
+    for (const code of codes) {
+      const msg = rpcError(new ConnectError("detail", code), resource).message;
+      expect(msg, `code ${Code[code]}`).toBeTruthy();
+    }
+  });
+});

package/src/domains/rpcerr.ts

@@ -0,0 +1,46 @@
+// Translation of transport/RPC failures into user-facing tool errors.
+//
+// Parity contract (mirrors Go internal/domains/rpcerr.go): the original error is
+// logged at WARN for operator debugging; only the classified, user-friendly
+// message is returned to the AI client. Message text is kept verbatim so the
+// TS and Go servers are indistinguishable to clients.
+
+import { Code, ConnectError } from "@connectrpc/connect";
+import { log } from "../logger.js";
+
+/**
+ * Translate a Connect/gRPC error into a user-friendly Error.
+ *
+ * `resourceDescription` identifies what was being accessed, e.g.
+ * `agent "code-reviewer" in org "stigmer"`.
+ */
+export function rpcError(err: unknown, resourceDescription: string): Error {
+  const ce = ConnectError.from(err);
+
+  log.warn("rpc call failed", {
+    resource: resourceDescription,
+    code: Code[ce.code],
+    grpc_message: ce.rawMessage,
+  });
+
+  return new Error(classifyCode(ce, resourceDescription));
+}
+
+function classifyCode(ce: ConnectError, resourceDescription: string): string {
+  switch (ce.code) {
+    case Code.NotFound:
+      return `${resourceDescription} not found. Verify the org and slug are correct.`;
+    case Code.PermissionDenied:
+      return `Permission denied for ${resourceDescription}. Check your API key permissions.`;
+    case Code.Unauthenticated:
+      return "Authentication failed. Check your API key.";
+    case Code.Unavailable:
+      return "Stigmer server is unavailable. Ensure it is running and reachable.";
+    case Code.DeadlineExceeded:
+      return "Request timed out contacting stigmer-server.";
+    case Code.InvalidArgument:
+      return ce.rawMessage;
+    default:
+      return `unexpected error: ${ce.rawMessage}`;
+  }
+}

package/src/domains/search/search.integration.test.ts

@@ -0,0 +1,127 @@
+// In-process integration test for the search tool. Verifies resource_uri
+// enrichment for all four searchable kinds, the empty-response short-circuit,
+// the unknown-kind validation error, and pagination passthrough.
+
+import { create, toJson } from "@bufbuild/protobuf";
+import type { ConnectRouter } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import {
+  createServer as createHttp2Server,
+  type Http2Server,
+  type ServerHttp2Session,
+} from "node:http2";
+import type { AddressInfo } from "node:net";
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { PageInfo } from "@stigmer/protos/ai/stigmer/commons/rpc/pagination_pb";
+import {
+  type SearchResponse,
+  SearchResponseSchema,
+  SearchResultSchema,
+} from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import { SearchService } from "@stigmer/protos/ai/stigmer/search/v1/query_pb";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { configureLogger } from "../../logger";
+import { createServer } from "../../server";
+
+configureLogger({ level: "error", format: "text" });
+
+const allKindsResponse = create(SearchResponseSchema, {
+  entries: [
+    create(SearchResultSchema, { kind: ApiResourceKind.agent, org: "acme", slug: "code-reviewer" }),
+    create(SearchResultSchema, { kind: ApiResourceKind.skill, org: "acme", slug: "code-review" }),
+    create(SearchResultSchema, { kind: ApiResourceKind.mcp_server, org: "acme", slug: "github" }),
+    create(SearchResultSchema, { kind: ApiResourceKind.workflow, org: "acme", slug: "release" }),
+  ],
+});
+const emptyResponse = create(SearchResponseSchema, { entries: [] });
+
+let backend: Http2Server;
+let client: Client;
+let nextResponse: SearchResponse = allKindsResponse;
+let lastPage: PageInfo | undefined;
+const openSessions = new Set<ServerHttp2Session>();
+
+interface ToolResult {
+  content: Array<{ type: string; text?: string }>;
+  isError?: boolean;
+}
+
+async function callSearch(args: Record<string, unknown>): Promise<ToolResult> {
+  return (await client.callTool({ name: "search", arguments: args })) as ToolResult;
+}
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(SearchService, {
+      search: (req) => {
+        lastPage = req.page;
+        return nextResponse;
+      },
+    });
+  };
+  backend = createHttp2Server(connectNodeAdapter({ routes }));
+  backend.on("session", (session) => {
+    openSessions.add(session);
+    session.on("close", () => openSessions.delete(session));
+  });
+  await new Promise<void>((resolve) => backend.listen(0, "127.0.0.1", resolve));
+  const port = (backend.address() as AddressInfo).port;
+
+  const mcp = createServer({ serverAddress: `127.0.0.1:${port}`, apiKey: "" });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  client = new Client({ name: "search-integration", version: "test" });
+  await Promise.all([mcp.connect(serverTransport), client.connect(clientTransport)]);
+});
+
+afterAll(async () => {
+  await client?.close();
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+describe("search tool integration", () => {
+  it("enriches every kind with a resource_uri", async () => {
+    nextResponse = allKindsResponse;
+    const result = await callSearch({ query: "code" });
+    expect(result.isError).toBeFalsy();
+    const data = JSON.parse(result.content[0]?.text ?? "{}") as {
+      entries: Array<{ resource_uri?: string }>;
+    };
+    expect(data.entries.map((e) => e.resource_uri)).toEqual([
+      "stigmer://agents/acme/code-reviewer",
+      "stigmer://skills/acme/code-review",
+      "stigmer://mcp-servers/acme/github",
+      "stigmer://workflows/acme/release",
+    ]);
+  });
+
+  it("short-circuits an empty response to the plain marshal", async () => {
+    nextResponse = emptyResponse;
+    const result = await callSearch({ query: "nothing" });
+    expect(result.isError).toBeFalsy();
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual(
+      toJson(SearchResponseSchema, emptyResponse, { useProtoFieldName: true }),
+    );
+  });
+
+  it("rejects an unknown kind without calling the backend", async () => {
+    const result = await callSearch({ kinds: ["bogus"] });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]?.text).toContain('unknown resource kind "bogus"');
+    expect(result.content[0]?.text).toContain("valid kinds: agent, skill, mcp_server, workflow");
+  });
+
+  it("forwards pagination only when requested", async () => {
+    nextResponse = allKindsResponse;
+    lastPage = undefined;
+    await callSearch({ query: "code" });
+    expect(lastPage).toBeUndefined();
+
+    await callSearch({ query: "code", page_size: 5, page_num: 2 });
+    expect(lastPage).toMatchObject({ size: 5, num: 2 });
+  });
+});

package/src/domains/search/tools.ts

@@ -0,0 +1,160 @@
+// The "search" MCP tool, backed by SearchService.search.
+// Go parity: mcp-server/internal/domains/search/tools.go.
+//
+// One tool covers listing, full-text search, and cross-kind discovery (replacing
+// per-kind list_* tools); the combination of parameters selects the behavior.
+// Each result entry is enriched with a resource_uri that clients can hand
+// straight to resources/read, bridging discovery to read.
+
+import { toJson, type MessageInitShape } from "@bufbuild/protobuf";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import {
+  type SearchRequestSchema,
+  type SearchResponse,
+  SearchResponseSchema,
+} from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import { SearchService } from "@stigmer/protos/ai/stigmer/search/v1/query_pb";
+import { z } from "zod";
+
+import { resolveToken, withClient, type BackendTarget } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { buildResourceURI } from "../resourceuri.js";
+import { rpcError } from "../rpcerr.js";
+import { textOrError } from "../toolresult.js";
+
+/**
+ * The searchable kinds and their proto enum values. This is deliberately the
+ * four searchable kinds (not every ApiResourceKind), mirroring the Go server's
+ * `knownKinds` map and its validation surface.
+ */
+const knownKinds: Readonly<Record<string, ApiResourceKind>> = {
+  agent: ApiResourceKind.agent,
+  skill: ApiResourceKind.skill,
+  mcp_server: ApiResourceKind.mcp_server,
+  workflow: ApiResourceKind.workflow,
+};
+
+interface SearchArgs {
+  readonly kinds?: string[];
+  readonly query?: string;
+  readonly org?: string;
+  readonly excludePublic?: boolean;
+  readonly pageSize?: number;
+  readonly pageNum?: number;
+}
+
+/** Register the search tool; returns the registered tool names. */
+export function registerSearchTools(server: McpServer, target: BackendTarget): string[] {
+  server.registerTool(
+    "search",
+    {
+      description:
+        "Search and list Stigmer resources (agents, skills, MCP servers, workflows). " +
+        "Set 'kinds' to filter by resource type. Set 'query' for full-text search. " +
+        "Set 'org' to scope to an organization. Omit 'query' to list all accessible resources.",
+      inputSchema: {
+        kinds: z
+          .array(z.string())
+          .optional()
+          .describe("Resource kinds to search. Valid: agent, skill, mcp_server, workflow. Empty searches all."),
+        query: z
+          .string()
+          .optional()
+          .describe("Full-text search query. Empty lists all accessible resources."),
+        org: z
+          .string()
+          .optional()
+          .describe("Organization slug to scope the search. Empty searches all accessible orgs."),
+        exclude_public: z
+          .boolean()
+          .optional()
+          .describe("Exclude public/platform resources from results."),
+        page_size: z.number().int().optional().describe("Results per page (default 20, max 100)."),
+        page_num: z.number().int().optional().describe("Page number (1-indexed, default 1)."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        search(target.serverAddress, resolveToken(extra, target.apiKey), {
+          kinds: args.kinds,
+          query: args.query,
+          org: args.org,
+          excludePublic: args.exclude_public,
+          pageSize: args.page_size,
+          pageNum: args.page_num,
+        }),
+      ),
+  );
+
+  return ["search"];
+}
+
+/** Run the search RPC and return the enriched protojson result. */
+async function search(serverAddress: string, token: string, args: SearchArgs): Promise<string> {
+  const kinds = parseKinds(args.kinds);
+  return withClient(SearchService, serverAddress, token, async (client, callOptions) => {
+    const req: MessageInitShape<typeof SearchRequestSchema> = {
+      kinds,
+      query: args.query ?? "",
+      org: args.org ?? "",
+      excludePublic: args.excludePublic ?? false,
+    };
+    // Attach pagination only when explicitly requested, letting the server apply
+    // its own defaults otherwise (Go does the same).
+    if ((args.pageSize ?? 0) > 0 || (args.pageNum ?? 0) > 0) {
+      req.page = { size: args.pageSize ?? 0, num: args.pageNum ?? 0 };
+    }
+
+    let resp: SearchResponse;
+    try {
+      resp = await client.search(req, callOptions);
+    } catch (err) {
+      throw rpcError(err, args.org ? `search results in org "${args.org}"` : "search results");
+    }
+    return enrichSearchResponse(resp);
+  });
+}
+
+/** Convert user-supplied kind strings to proto enum values, rejecting unknowns. */
+function parseKinds(raw: string[] | undefined): ApiResourceKind[] {
+  if (!raw || raw.length === 0) {
+    return [];
+  }
+  return raw.map((s) => {
+    const kind = knownKinds[s];
+    if (kind === undefined) {
+      throw new Error(
+        `unknown resource kind "${s}"; valid kinds: agent, skill, mcp_server, workflow`,
+      );
+    }
+    return kind;
+  });
+}
+
+/**
+ * Serialize the response and inject a resource_uri into each entry whose kind
+ * has a registered resource template. Empty responses short-circuit to the plain
+ * marshal to avoid the walk.
+ */
+function enrichSearchResponse(resp: SearchResponse): string {
+  if (resp.entries.length === 0) {
+    return toProtoJson(SearchResponseSchema, resp);
+  }
+
+  const data = toJson(SearchResponseSchema, resp, { useProtoFieldName: true }) as Record<
+    string,
+    unknown
+  >;
+  const entries = Array.isArray(data.entries)
+    ? (data.entries as Array<Record<string, unknown>>)
+    : [];
+  for (let i = 0; i < entries.length && i < resp.entries.length; i++) {
+    const r = resp.entries[i]!;
+    const uri = buildResourceURI(ApiResourceKind[r.kind] ?? "", r.org, r.slug);
+    if (uri !== "") {
+      entries[i]!.resource_uri = uri;
+    }
+  }
+  return JSON.stringify(data, null, 2);
+}

package/src/domains/skills/delete.ts

@@ -0,0 +1,44 @@
+// Skill delete path: resolve org/slug → id, then delete (removing the skill and
+// all its versions), both over a single shared transport.
+// Go parity: mcp-server/internal/domains/skills/delete.go.
+
+import { createClient } from "@connectrpc/connect";
+import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import { SkillCommandController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/command_pb";
+import { SkillQueryController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/query_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { withTransport } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+/**
+ * Delete a skill and all its versions by org and slug, returning the deleted
+ * skill as protojson.
+ */
+export async function deleteSkill(
+  serverAddress: string,
+  token: string,
+  org: string,
+  slug: string,
+): Promise<string> {
+  const desc = `skill "${slug}" in org "${org}"`;
+  return withTransport(serverAddress, token, async (transport, callOptions) => {
+    const query = createClient(SkillQueryController, transport);
+    let id: string;
+    try {
+      const skill = await query.getByReference({ org, kind: ApiResourceKind.skill, slug }, callOptions);
+      id = skill.metadata?.id ?? "";
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+
+    const command = createClient(SkillCommandController, transport);
+    try {
+      const deleted = await command.delete({ value: id }, callOptions);
+      return toProtoJson(SkillSchema, deleted);
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+  });
+}