feat(skills): user_skills table + /v1/skills CRUD (custom skills backend)

Author: iamjr15

apps/gateway-worker/src/index.ts

@@ -97,6 +97,7 @@ import {
   updateReplayShareRoute,
 } from "./replay-share-routes";
 import { searchWorkspaceRoute } from "./search-routes";
+import { createUserSkillRoute, deleteUserSkillRoute, listUserSkillsRoute } from "./skills-routes";
 import { clientErrorRoute, clientUserEventRoute, vitalsRoute } from "./telemetry-routes";
 import { listUsageDailyRoute } from "./usage-routes";
 
@@ -310,6 +311,21 @@ export const gatewayRoutes = gatewayApp
     await rateLimit(c, userId, "GET /v1/threads/:threadId/replay-share");
     return getThreadReplayShareRoute(c.env, c.executionCtx, userId, c.req.param("threadId"));
   })
+  .get("/v1/skills", async (c) => {
+    const userId = await authenticate(c.req.raw, c.env, c.executionCtx);
+    await rateLimit(c, userId, "GET /v1/skills");
+    return listUserSkillsRoute(c.env, c.executionCtx, userId);
+  })
+  .post("/v1/skills", async (c) => {
+    const userId = await authenticate(c.req.raw, c.env, c.executionCtx);
+    await rateLimit(c, userId, "POST /v1/skills");
+    return createUserSkillRoute(c.env, c.executionCtx, c.req.raw, userId);
+  })
+  .delete("/v1/skills/:skillId", async (c) => {
+    const userId = await authenticate(c.req.raw, c.env, c.executionCtx);
+    await rateLimit(c, userId, "DELETE /v1/skills/:skillId");
+    return deleteUserSkillRoute(c.env, c.executionCtx, userId, c.req.param("skillId"));
+  })
   .get("/v1/me", async (c) => {
     const userId = await authenticate(c.req.raw, c.env, c.executionCtx);
     await rateLimit(c, userId, "GET /v1/me");

apps/gateway-worker/src/skills-routes.ts

@@ -0,0 +1,108 @@
+import {
+  createDb,
+  deleteUserSkill,
+  listUserSkills,
+  type UserSkillRecord,
+  upsertUserSkill,
+  withUserContext,
+} from "@cheatcode/db";
+import { APIError } from "@cheatcode/observability";
+import {
+  CreateUserSkillSchema,
+  type UserId,
+  UserSkillSchema,
+  UserSkillsResponseSchema,
+} from "@cheatcode/types";
+import { z } from "zod";
+import type { GatewayEnv } from "./index";
+
+const IdParamSchema = z.string().uuid();
+const DEFAULT_SKILL_CATEGORY = "Builder & Apps";
+
+function skillSummary(record: UserSkillRecord): unknown {
+  return UserSkillSchema.parse({
+    category: record.category,
+    createdAt: record.createdAt.toISOString(),
+    description: record.description,
+    id: record.id,
+    name: record.name,
+    tags: record.tags,
+    updatedAt: record.updatedAt.toISOString(),
+  });
+}
+
+/** `GET /v1/skills` — the caller's custom skills (body-less summaries). */
+export async function listUserSkillsRoute(
+  env: GatewayEnv,
+  ctx: ExecutionContext,
+  userId: UserId,
+): Promise<Response> {
+  const { db, close } = createDb(env.HYPERDRIVE);
+  try {
+    const rows = await withUserContext(db, userId, (tx) => listUserSkills(tx, userId));
+    return Response.json(UserSkillsResponseSchema.parse({ skills: rows.map(skillSummary) }));
+  } finally {
+    ctx.waitUntil(close());
+  }
+}
+
+/**
+ * `POST /v1/skills` — create or update (by name) a custom skill. Used by the agent's
+ * `skill_create` tool path and the manual creation form.
+ */
+export async function createUserSkillRoute(
+  env: GatewayEnv,
+  ctx: ExecutionContext,
+  request: Request,
+  userId: UserId,
+): Promise<Response> {
+  const parsed = CreateUserSkillSchema.safeParse(await request.json());
+  if (!parsed.success) {
+    throw new APIError(400, "invalid_request_body", "Invalid skill payload", {
+      details: { issues: parsed.error.issues.map((issue) => issue.message) },
+      retriable: false,
+    });
+  }
+  const input = parsed.data;
+  const { db, close } = createDb(env.HYPERDRIVE);
+  try {
+    const record = await withUserContext(db, userId, (tx) =>
+      upsertUserSkill(tx, {
+        body: input.body,
+        category: input.category ?? DEFAULT_SKILL_CATEGORY,
+        description: input.description,
+        name: input.name,
+        tags: input.tags ?? [],
+        userId,
+      }),
+    );
+    return Response.json(skillSummary(record), { status: 201 });
+  } finally {
+    ctx.waitUntil(close());
+  }
+}
+
+/** `DELETE /v1/skills/:id` — soft-delete a custom skill the caller owns. */
+export async function deleteUserSkillRoute(
+  env: GatewayEnv,
+  ctx: ExecutionContext,
+  userId: UserId,
+  skillId: string,
+): Promise<Response> {
+  const parsed = IdParamSchema.safeParse(skillId);
+  if (!parsed.success) {
+    throw new APIError(400, "invalid_path_param", "Invalid skill id", { retriable: false });
+  }
+  const { db, close } = createDb(env.HYPERDRIVE);
+  try {
+    const deleted = await withUserContext(db, userId, (tx) =>
+      deleteUserSkill(tx, userId, parsed.data),
+    );
+    if (!deleted) {
+      throw new APIError(404, "not_found_skill", "Skill not found", { retriable: false });
+    }
+    return new Response(null, { status: 204 });
+  } finally {
+    ctx.waitUntil(close());
+  }
+}

infra/supabase/migrations/post/0027_v2_user_skills_grants.sql

@@ -0,0 +1,11 @@
+-- User-created skills grants. Same posture as the other per-user tables: no
+-- row-level security (RLS stays limited to v2_provider_keys + v2_audit_log), with
+-- per-user isolation enforced in application code via withUserContext + userId
+-- filters. Skill bodies are user-authored markdown — no provider secrets at rest.
+--
+-- DSR / account deletion: the user_id foreign key cascades on delete, so removing
+-- a v2_users row tears down its custom skills automatically.
+
+grant select, insert, update, delete on table
+  v2_user_skills
+to app_worker;

packages/db/drizzle/0007_ambiguous_thunderball.sql

@@ -0,0 +1,16 @@
+CREATE TABLE "v2_user_skills" (
+	"id" uuid PRIMARY KEY DEFAULT public.uuidv7() NOT NULL,
+	"user_id" uuid NOT NULL,
+	"name" text NOT NULL,
+	"description" text NOT NULL,
+	"category" text NOT NULL,
+	"tags" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"body" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"deleted_at" timestamp with time zone
+);
+--> statement-breakpoint
+ALTER TABLE "v2_user_skills" ADD CONSTRAINT "v2_user_skills_user_id_v2_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."v2_users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "v2_user_skills_user_idx" ON "v2_user_skills" USING btree ("user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "v2_user_skills_user_name_idx" ON "v2_user_skills" USING btree ("user_id","name") WHERE deleted_at is null;