Add company skill assignment to agent create and hire flows

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-03-18 13:18:48 -05:00
parent 099c37c4b4
commit 480174367d
12 changed files with 699 additions and 35 deletions
--- a/server/src/tests/agent-skills-routes.test.ts
+++ b/server/src/tests/agent-skills-routes.test.ts
@@ -7,6 +7,7 @@ import { errorHandler } from "../middleware/index.js";
 const mockAgentService = vi.hoisted(() => ({
  getById: vi.fn(),
  update: vi.fn(),
+  create: vi.fn(),
  resolveByReference: vi.fn(),
 }));

@@ -18,7 +19,9 @@ const mockAccessService = vi.hoisted(() => ({
 const mockApprovalService = vi.hoisted(() => ({}));
 const mockBudgetService = vi.hoisted(() => ({}));
 const mockHeartbeatService = vi.hoisted(() => ({}));
-const mockIssueApprovalService = vi.hoisted(() => ({}));
+const mockIssueApprovalService = vi.hoisted(() => ({
+  linkManyForApproval: vi.fn(),
+}));
 const mockWorkspaceOperationService = vi.hoisted(() => ({}));
 const mockAgentInstructionsService = vi.hoisted(() => ({
  getBundle: vi.fn(),
@@ -33,6 +36,7 @@ const mockAgentInstructionsService = vi.hoisted(() => ({

 const mockCompanySkillService = vi.hoisted(() => ({
  listRuntimeSkillEntries: vi.fn(),
+  resolveRequestedSkillKeys: vi.fn(),
 }));

 const mockSecretService = vi.hoisted(() => ({
@@ -68,7 +72,22 @@ vi.mock("../adapters/index.js", () => ({
  listAdapterModels: vi.fn(),
 }));

-function createApp() {
+function createDb(requireBoardApprovalForNewAgents = false) {
+  return {
+    select: vi.fn(() => ({
+      from: vi.fn(() => ({
+        where: vi.fn(async () => [
+          {
+            id: "company-1",
+            requireBoardApprovalForNewAgents,
+          },
+        ]),
+      })),
+    })),
+  };
+}
+
+function createApp(db: Record<string, unknown> = createDb()) {
  const app = express();
  app.use(express.json());
  app.use((req, _res, next) => {
@@ -81,7 +100,7 @@ function createApp() {
    };
    next();
  });
-  app.use("/api", agentRoutes({} as any));
+  app.use("/api", agentRoutes(db as any));
  app.use(errorHandler);
  return app;
 }
@@ -121,6 +140,14 @@ describe("agent skill routes", () => {
        requiredReason: "required",
      },
    ]);
+    mockCompanySkillService.resolveRequestedSkillKeys.mockImplementation(
+      async (_companyId: string, requested: string[]) =>
+        requested.map((value) =>
+          value === "paperclip"
+            ? "paperclipai/paperclip/paperclip"
+            : value,
+        ),
+    );
    mockAdapter.listSkills.mockResolvedValue({
      adapterType: "claude_local",
      supported: true,
@@ -141,7 +168,24 @@ describe("agent skill routes", () => {
      ...makeAgent("claude_local"),
      adapterConfig: patch.adapterConfig ?? {},
    }));
+    mockAgentService.create.mockImplementation(async (_companyId: string, input: Record<string, unknown>) => ({
+      ...makeAgent(String(input.adapterType ?? "claude_local")),
+      ...input,
+      adapterConfig: input.adapterConfig ?? {},
+      runtimeConfig: input.runtimeConfig ?? {},
+      budgetMonthlyCents: Number(input.budgetMonthlyCents ?? 0),
+      permissions: null,
+    }));
+    mockApprovalService.create = vi.fn(async (_companyId: string, input: Record<string, unknown>) => ({
+      id: "approval-1",
+      companyId: "company-1",
+      type: "hire_agent",
+      status: "pending",
+      payload: input.payload ?? {},
+    }));
    mockLogActivity.mockResolvedValue(undefined);
+    mockAccessService.canUser.mockResolvedValue(true);
+    mockAccessService.hasPermission.mockResolvedValue(true);
  });

  it("skips runtime materialization when listing Claude skills", async () => {
@@ -197,4 +241,79 @@ describe("agent skill routes", () => {
    });
    expect(mockAdapter.syncSkills).toHaveBeenCalled();
  });
+
+  it("canonicalizes desired skill references before syncing", async () => {
+    mockAgentService.getById.mockResolvedValue(makeAgent("claude_local"));
+
+    const res = await request(createApp())
+      .post("/api/agents/11111111-1111-4111-8111-111111111111/skills/sync?companyId=company-1")
+      .send({ desiredSkills: ["paperclip"] });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(200);
+    expect(mockCompanySkillService.resolveRequestedSkillKeys).toHaveBeenCalledWith("company-1", ["paperclip"]);
+    expect(mockAgentService.update).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        adapterConfig: expect.objectContaining({
+          paperclipSkillSync: expect.objectContaining({
+            desiredSkills: ["paperclipai/paperclip/paperclip"],
+          }),
+        }),
+      }),
+      expect.any(Object),
+    );
+  });
+
+  it("persists canonical desired skills when creating an agent directly", async () => {
+    const res = await request(createApp())
+      .post("/api/companies/company-1/agents")
+      .send({
+        name: "QA Agent",
+        role: "engineer",
+        adapterType: "claude_local",
+        desiredSkills: ["paperclip"],
+        adapterConfig: {},
+      });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(201);
+    expect(mockCompanySkillService.resolveRequestedSkillKeys).toHaveBeenCalledWith("company-1", ["paperclip"]);
+    expect(mockAgentService.create).toHaveBeenCalledWith(
+      "company-1",
+      expect.objectContaining({
+        adapterConfig: expect.objectContaining({
+          paperclipSkillSync: expect.objectContaining({
+            desiredSkills: ["paperclipai/paperclip/paperclip"],
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("includes canonical desired skills in hire approvals", async () => {
+    const db = createDb(true);
+
+    const res = await request(createApp(db))
+      .post("/api/companies/company-1/agent-hires")
+      .send({
+        name: "QA Agent",
+        role: "engineer",
+        adapterType: "claude_local",
+        desiredSkills: ["paperclip"],
+        adapterConfig: {},
+      });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(201);
+    expect(mockCompanySkillService.resolveRequestedSkillKeys).toHaveBeenCalledWith("company-1", ["paperclip"]);
+    expect(mockApprovalService.create).toHaveBeenCalledWith(
+      "company-1",
+      expect.objectContaining({
+        payload: expect.objectContaining({
+          desiredSkills: ["paperclipai/paperclip/paperclip"],
+          requestedConfigurationSnapshot: expect.objectContaining({
+            desiredSkills: ["paperclipai/paperclip/paperclip"],
+          }),
+        }),
+      }),
+    );
+  });
 });
--- a/server/src/tests/company-skills-routes.test.ts
+++ b/server/src/tests/company-skills-routes.test.ts
@@ -0,0 +1,113 @@
+import express from "express";
+import request from "supertest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { companySkillRoutes } from "../routes/company-skills.js";
+import { errorHandler } from "../middleware/index.js";
+
+const mockAgentService = vi.hoisted(() => ({
+  getById: vi.fn(),
+}));
+
+const mockAccessService = vi.hoisted(() => ({
+  canUser: vi.fn(),
+  hasPermission: vi.fn(),
+}));
+
+const mockCompanySkillService = vi.hoisted(() => ({
+  importFromSource: vi.fn(),
+}));
+
+const mockLogActivity = vi.hoisted(() => vi.fn());
+
+vi.mock("../services/index.js", () => ({
+  accessService: () => mockAccessService,
+  agentService: () => mockAgentService,
+  companySkillService: () => mockCompanySkillService,
+  logActivity: mockLogActivity,
+}));
+
+function createApp(actor: Record<string, unknown>) {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    (req as any).actor = actor;
+    next();
+  });
+  app.use("/api", companySkillRoutes({} as any));
+  app.use(errorHandler);
+  return app;
+}
+
+describe("company skill mutation permissions", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCompanySkillService.importFromSource.mockResolvedValue({
+      imported: [],
+      warnings: [],
+    });
+    mockLogActivity.mockResolvedValue(undefined);
+    mockAccessService.canUser.mockResolvedValue(true);
+    mockAccessService.hasPermission.mockResolvedValue(false);
+  });
+
+  it("allows local board operators to mutate company skills", async () => {
+    const res = await request(createApp({
+      type: "board",
+      userId: "local-board",
+      companyIds: ["company-1"],
+      source: "local_implicit",
+      isInstanceAdmin: false,
+    }))
+      .post("/api/companies/company-1/skills/import")
+      .send({ source: "https://github.com/vercel-labs/agent-browser" });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(201);
+    expect(mockCompanySkillService.importFromSource).toHaveBeenCalledWith(
+      "company-1",
+      "https://github.com/vercel-labs/agent-browser",
+    );
+  });
+
+  it("blocks same-company agents without management permission from mutating company skills", async () => {
+    mockAgentService.getById.mockResolvedValue({
+      id: "agent-1",
+      companyId: "company-1",
+      permissions: {},
+    });
+
+    const res = await request(createApp({
+      type: "agent",
+      agentId: "agent-1",
+      companyId: "company-1",
+      runId: "run-1",
+    }))
+      .post("/api/companies/company-1/skills/import")
+      .send({ source: "https://github.com/vercel-labs/agent-browser" });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(403);
+    expect(mockCompanySkillService.importFromSource).not.toHaveBeenCalled();
+  });
+
+  it("allows agents with canCreateAgents to mutate company skills", async () => {
+    mockAgentService.getById.mockResolvedValue({
+      id: "agent-1",
+      companyId: "company-1",
+      permissions: { canCreateAgents: true },
+    });
+
+    const res = await request(createApp({
+      type: "agent",
+      agentId: "agent-1",
+      companyId: "company-1",
+      runId: "run-1",
+    }))
+      .post("/api/companies/company-1/skills/import")
+      .send({ source: "https://github.com/vercel-labs/agent-browser" });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(201);
+    expect(mockCompanySkillService.importFromSource).toHaveBeenCalledWith(
+      "company-1",
+      "https://github.com/vercel-labs/agent-browser",
+    );
+  });
+});
--- a/server/src/routes/agents.ts
+++ b/server/src/routes/agents.ts
@@ -394,6 +394,39 @@ export function agentRoutes(db: Db) {
    };
  }

+  async function resolveDesiredSkillAssignment(
+    companyId: string,
+    adapterType: string,
+    adapterConfig: Record<string, unknown>,
+    requestedDesiredSkills: string[] | undefined,
+  ) {
+    if (!requestedDesiredSkills) {
+      return {
+        adapterConfig,
+        desiredSkills: null as string[] | null,
+        runtimeSkillEntries: null as Awaited<ReturnType<typeof companySkills.listRuntimeSkillEntries>> | null,
+      };
+    }
+
+    const resolvedRequestedSkills = await companySkills.resolveRequestedSkillKeys(
+      companyId,
+      requestedDesiredSkills,
+    );
+    const runtimeSkillEntries = await companySkills.listRuntimeSkillEntries(companyId, {
+      materializeMissing: shouldMaterializeRuntimeSkillsForAdapter(adapterType),
+    });
+    const requiredSkills = runtimeSkillEntries
+      .filter((entry) => entry.required)
+      .map((entry) => entry.key);
+    const desiredSkills = Array.from(new Set([...requiredSkills, ...resolvedRequestedSkills]));
+
+    return {
+      adapterConfig: writePaperclipSkillSyncPreference(adapterConfig, desiredSkills),
+      desiredSkills,
+      runtimeSkillEntries,
+    };
+  }
+
  function redactForRestrictedAgentView(agent: Awaited<ReturnType<typeof svc.getById>>) {
    if (!agent) return null;
    return {
@@ -578,15 +611,19 @@ export function agentRoutes(db: Db) {
            .filter(Boolean),
        ),
      );
-      const runtimeSkillEntries = await companySkills.listRuntimeSkillEntries(agent.companyId, {
-        materializeMissing: shouldMaterializeRuntimeSkillsForAdapter(agent.adapterType),
-      });
-      const requiredSkills = runtimeSkillEntries.filter((entry) => entry.required).map((entry) => entry.key);
-      const desiredSkills = Array.from(new Set([...requiredSkills, ...requestedSkills]));
-      const nextAdapterConfig = writePaperclipSkillSyncPreference(
-        agent.adapterConfig as Record<string, unknown>,
+      const {
+        adapterConfig: nextAdapterConfig,
        desiredSkills,
+        runtimeSkillEntries,
+      } = await resolveDesiredSkillAssignment(
+        agent.companyId,
+        agent.adapterType,
+        agent.adapterConfig as Record<string, unknown>,
+        requestedSkills,
      );
+      if (!desiredSkills || !runtimeSkillEntries) {
+        throw unprocessable("Skill sync requires desiredSkills.");
+      }
      const actor = getActorInfo(req);
      const updated = await svc.update(agent.id, {
        adapterConfig: nextAdapterConfig,
@@ -955,14 +992,25 @@ export function agentRoutes(db: Db) {
    const companyId = req.params.companyId as string;
    await assertCanCreateAgentsForCompany(req, companyId);
    const sourceIssueIds = parseSourceIssueIds(req.body);
-    const { sourceIssueId: _sourceIssueId, sourceIssueIds: _sourceIssueIds, ...hireInput } = req.body;
+    const {
+      desiredSkills: requestedDesiredSkills,
+      sourceIssueId: _sourceIssueId,
+      sourceIssueIds: _sourceIssueIds,
+      ...hireInput
+    } = req.body;
    const requestedAdapterConfig = applyCreateDefaultsByAdapterType(
      hireInput.adapterType,
      ((hireInput.adapterConfig ?? {}) as Record<string, unknown>),
    );
+    const desiredSkillAssignment = await resolveDesiredSkillAssignment(
+      companyId,
+      hireInput.adapterType,
+      requestedAdapterConfig,
+      Array.isArray(requestedDesiredSkills) ? requestedDesiredSkills : undefined,
+    );
    const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(
      companyId,
-      requestedAdapterConfig,
+      desiredSkillAssignment.adapterConfig,
      { strictMode: strictSecretsMode },
    );
    await assertAdapterConfigConstraints(
@@ -1030,6 +1078,7 @@ export function agentRoutes(db: Db) {
            typeof normalizedHireInput.budgetMonthlyCents === "number"
              ? normalizedHireInput.budgetMonthlyCents
              : agent.budgetMonthlyCents,
+          desiredSkills: desiredSkillAssignment.desiredSkills,
          metadata: requestedMetadata,
          agentId: agent.id,
          requestedByAgentId: actor.actorType === "agent" ? actor.actorId : null,
@@ -1037,6 +1086,7 @@ export function agentRoutes(db: Db) {
            adapterType: requestedAdapterType,
            adapterConfig: requestedAdapterConfig,
            runtimeConfig: requestedRuntimeConfig,
+            desiredSkills: desiredSkillAssignment.desiredSkills,
          },
        },
        decisionNote: null,
@@ -1068,6 +1118,7 @@ export function agentRoutes(db: Db) {
        requiresApproval,
        approvalId: approval?.id ?? null,
        issueIds: sourceIssueIds,
+        desiredSkills: desiredSkillAssignment.desiredSkills,
      },
    });

@@ -1096,23 +1147,33 @@ export function agentRoutes(db: Db) {
      assertBoard(req);
    }

+    const {
+      desiredSkills: requestedDesiredSkills,
+      ...createInput
+    } = req.body;
    const requestedAdapterConfig = applyCreateDefaultsByAdapterType(
-      req.body.adapterType,
-      ((req.body.adapterConfig ?? {}) as Record<string, unknown>),
+      createInput.adapterType,
+      ((createInput.adapterConfig ?? {}) as Record<string, unknown>),
+    );
+    const desiredSkillAssignment = await resolveDesiredSkillAssignment(
+      companyId,
+      createInput.adapterType,
+      requestedAdapterConfig,
+      Array.isArray(requestedDesiredSkills) ? requestedDesiredSkills : undefined,
    );
    const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(
      companyId,
-      requestedAdapterConfig,
+      desiredSkillAssignment.adapterConfig,
      { strictMode: strictSecretsMode },
    );
    await assertAdapterConfigConstraints(
      companyId,
-      req.body.adapterType,
+      createInput.adapterType,
      normalizedAdapterConfig,
    );

    const agent = await svc.create(companyId, {
-      ...req.body,
+      ...createInput,
      adapterConfig: normalizedAdapterConfig,
      status: "idle",
      spentMonthlyCents: 0,
@@ -1129,7 +1190,11 @@ export function agentRoutes(db: Db) {
      action: "agent.created",
      entityType: "agent",
      entityId: agent.id,
-      details: { name: agent.name, role: agent.role },
+      details: {
+        name: agent.name,
+        role: agent.role,
+        desiredSkills: desiredSkillAssignment.desiredSkills,
+      },
    });

    if (agent.budgetMonthlyCents > 0) {
--- a/server/src/routes/company-skills.ts
+++ b/server/src/routes/company-skills.ts
@@ -1,4 +1,4 @@
-import { Router } from "express";
+import { Router, type Request } from "express";
 import type { Db } from "@paperclipai/db";
 import {
  companySkillCreateSchema,
@@ -7,13 +7,50 @@ import {
  companySkillProjectScanRequestSchema,
 } from "@paperclipai/shared";
 import { validate } from "../middleware/validate.js";
-import { companySkillService, logActivity } from "../services/index.js";
+import { accessService, agentService, companySkillService, logActivity } from "../services/index.js";
+import { forbidden } from "../errors.js";
 import { assertCompanyAccess, getActorInfo } from "./authz.js";

 export function companySkillRoutes(db: Db) {
  const router = Router();
+  const agents = agentService(db);
+  const access = accessService(db);
  const svc = companySkillService(db);

+  function canCreateAgents(agent: { permissions: Record<string, unknown> | null | undefined }) {
+    if (!agent.permissions || typeof agent.permissions !== "object") return false;
+    return Boolean((agent.permissions as Record<string, unknown>).canCreateAgents);
+  }
+
+  async function assertCanMutateCompanySkills(req: Request, companyId: string) {
+    assertCompanyAccess(req, companyId);
+
+    if (req.actor.type === "board") {
+      if (req.actor.source === "local_implicit" || req.actor.isInstanceAdmin) return;
+      const allowed = await access.canUser(companyId, req.actor.userId, "agents:create");
+      if (!allowed) {
+        throw forbidden("Missing permission: agents:create");
+      }
+      return;
+    }
+
+    if (!req.actor.agentId) {
+      throw forbidden("Agent authentication required");
+    }
+
+    const actorAgent = await agents.getById(req.actor.agentId);
+    if (!actorAgent || actorAgent.companyId !== companyId) {
+      throw forbidden("Agent key cannot access another company");
+    }
+
+    const allowedByGrant = await access.hasPermission(companyId, "agent", actorAgent.id, "agents:create");
+    if (allowedByGrant || canCreateAgents(actorAgent)) {
+      return;
+    }
+
+    throw forbidden("Missing permission: can create agents");
+  }
+
  router.get("/companies/:companyId/skills", async (req, res) => {
    const companyId = req.params.companyId as string;
    assertCompanyAccess(req, companyId);
@@ -63,7 +100,7 @@ export function companySkillRoutes(db: Db) {
    validate(companySkillCreateSchema),
    async (req, res) => {
      const companyId = req.params.companyId as string;
-      assertCompanyAccess(req, companyId);
+      await assertCanMutateCompanySkills(req, companyId);
      const result = await svc.createLocalSkill(companyId, req.body);

      const actor = getActorInfo(req);
@@ -92,7 +129,7 @@ export function companySkillRoutes(db: Db) {
    async (req, res) => {
      const companyId = req.params.companyId as string;
      const skillId = req.params.skillId as string;
-      assertCompanyAccess(req, companyId);
+      await assertCanMutateCompanySkills(req, companyId);
      const result = await svc.updateFile(
        companyId,
        skillId,
@@ -125,7 +162,7 @@ export function companySkillRoutes(db: Db) {
    validate(companySkillImportSchema),
    async (req, res) => {
      const companyId = req.params.companyId as string;
-      assertCompanyAccess(req, companyId);
+      await assertCanMutateCompanySkills(req, companyId);
      const source = String(req.body.source ?? "");
      const result = await svc.importFromSource(companyId, source);

@@ -156,7 +193,7 @@ export function companySkillRoutes(db: Db) {
    validate(companySkillProjectScanRequestSchema),
    async (req, res) => {
      const companyId = req.params.companyId as string;
-      assertCompanyAccess(req, companyId);
+      await assertCanMutateCompanySkills(req, companyId);
      const result = await svc.scanProjectWorkspaces(companyId, req.body);

      const actor = getActorInfo(req);
@@ -187,7 +224,7 @@ export function companySkillRoutes(db: Db) {
  router.post("/companies/:companyId/skills/:skillId/install-update", async (req, res) => {
    const companyId = req.params.companyId as string;
    const skillId = req.params.skillId as string;
-    assertCompanyAccess(req, companyId);
+    await assertCanMutateCompanySkills(req, companyId);
    const result = await svc.installUpdate(companyId, skillId);
    if (!result) {
      res.status(404).json({ error: "Skill not found" });
--- a/server/src/services/company-skills.ts
+++ b/server/src/services/company-skills.ts
@@ -1065,17 +1065,79 @@ function getSkillMeta(skill: CompanySkill): SkillSourceMeta {
 function resolveSkillReference(
  skills: CompanySkill[],
  reference: string,
-): CompanySkill | null {
-  const normalizedReference = normalizeSkillKey(reference) ?? normalizeSkillSlug(reference);
-  if (!normalizedReference) return null;
+): { skill: CompanySkill | null; ambiguous: boolean } {
+  const trimmed = reference.trim();
+  if (!trimmed) {
+    return { skill: null, ambiguous: false };
+  }

-  const byKey = skills.find((skill) => skill.key === normalizedReference);
-  if (byKey) return byKey;
+  const byId = skills.find((skill) => skill.id === trimmed);
+  if (byId) {
+    return { skill: byId, ambiguous: false };
+  }

-  const bySlug = skills.filter((skill) => skill.slug === normalizedReference);
-  if (bySlug.length === 1) return bySlug[0] ?? null;
+  const normalizedKey = normalizeSkillKey(trimmed);
+  if (normalizedKey) {
+    const byKey = skills.find((skill) => skill.key === normalizedKey);
+    if (byKey) {
+      return { skill: byKey, ambiguous: false };
+    }
+  }

-  return null;
+  const normalizedSlug = normalizeSkillSlug(trimmed);
+  if (!normalizedSlug) {
+    return { skill: null, ambiguous: false };
+  }
+
+  const bySlug = skills.filter((skill) => skill.slug === normalizedSlug);
+  if (bySlug.length === 1) {
+    return { skill: bySlug[0] ?? null, ambiguous: false };
+  }
+  if (bySlug.length > 1) {
+    return { skill: null, ambiguous: true };
+  }
+
+  return { skill: null, ambiguous: false };
+}
+
+function resolveRequestedSkillKeysOrThrow(
+  skills: CompanySkill[],
+  requestedReferences: string[],
+) {
+  const missing = new Set<string>();
+  const ambiguous = new Set<string>();
+  const resolved = new Set<string>();
+
+  for (const reference of requestedReferences) {
+    const trimmed = reference.trim();
+    if (!trimmed) continue;
+
+    const match = resolveSkillReference(skills, trimmed);
+    if (match.skill) {
+      resolved.add(match.skill.key);
+      continue;
+    }
+
+    if (match.ambiguous) {
+      ambiguous.add(trimmed);
+      continue;
+    }
+
+    missing.add(trimmed);
+  }
+
+  if (ambiguous.size > 0 || missing.size > 0) {
+    const problems: string[] = [];
+    if (ambiguous.size > 0) {
+      problems.push(`ambiguous references: ${Array.from(ambiguous).sort().join(", ")}`);
+    }
+    if (missing.size > 0) {
+      problems.push(`unknown references: ${Array.from(missing).sort().join(", ")}`);
+    }
+    throw unprocessable(`Invalid company skill selection (${problems.join("; ")}).`);
+  }
+
+  return Array.from(resolved);
 }

 function resolveDesiredSkillKeys(
@@ -1085,7 +1147,7 @@ function resolveDesiredSkillKeys(
  const preference = readPaperclipSkillSyncPreference(config);
  return Array.from(new Set(
    preference.desiredSkills
-      .map((reference) => resolveSkillReference(skills, reference)?.key ?? normalizeSkillKey(reference))
+      .map((reference) => resolveSkillReference(skills, reference).skill?.key ?? normalizeSkillKey(reference))
      .filter((value): value is string => Boolean(value)),
  ));
 }
@@ -1952,6 +2014,10 @@ export function companySkillService(db: Db) {
    listFull,
    getById,
    getByKey,
+    resolveRequestedSkillKeys: async (companyId: string, requestedReferences: string[]) => {
+      const skills = await listFull(companyId);
+      return resolveRequestedSkillKeysOrThrow(skills, requestedReferences);
+    },
    detail,
    updateStatus,
    readFile,