Add adapter skill sync for codex and claude

packages/adapter-utils/src/index.ts

@@ -12,6 +12,11 @@ export type {
   AdapterEnvironmentTestStatus,
   AdapterEnvironmentTestResult,
   AdapterEnvironmentTestContext,
+  AdapterSkillSyncMode,
+  AdapterSkillState,
+  AdapterSkillEntry,
+  AdapterSkillSnapshot,
+  AdapterSkillContext,
   AdapterSessionCodec,
   AdapterModel,
   HireApprovedPayload,

packages/adapter-utils/src/server-utils.ts

@@ -330,6 +330,49 @@ export async function readPaperclipSkillMarkdown(
   }
 }
 
+export function readPaperclipSkillSyncPreference(config: Record<string, unknown>): {
+  explicit: boolean;
+  desiredSkills: string[];
+} {
+  const raw = config.paperclipSkillSync;
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { explicit: false, desiredSkills: [] };
+  }
+  const syncConfig = raw as Record<string, unknown>;
+  const desiredValues = syncConfig.desiredSkills;
+  const desired = Array.isArray(desiredValues)
+    ? desiredValues
+        .filter((value): value is string => typeof value === "string")
+        .map((value) => value.trim())
+        .filter(Boolean)
+    : [];
+  return {
+    explicit: Object.prototype.hasOwnProperty.call(raw, "desiredSkills"),
+    desiredSkills: Array.from(new Set(desired)),
+  };
+}
+
+export function writePaperclipSkillSyncPreference(
+  config: Record<string, unknown>,
+  desiredSkills: string[],
+): Record<string, unknown> {
+  const next = { ...config };
+  const raw = next.paperclipSkillSync;
+  const current =
+    typeof raw === "object" && raw !== null && !Array.isArray(raw)
+      ? { ...(raw as Record<string, unknown>) }
+      : {};
+  current.desiredSkills = Array.from(
+    new Set(
+      desiredSkills
+        .map((value) => value.trim())
+        .filter(Boolean),
+    ),
+  );
+  next.paperclipSkillSync = current;
+  return next;
+}
+
 export async function ensurePaperclipSkillSymlink(
   source: string,
   target: string,

packages/adapter-utils/src/types.ts

@@ -138,6 +138,42 @@ export interface AdapterEnvironmentTestResult {
   testedAt: string;
 }
 
+export type AdapterSkillSyncMode = "unsupported" | "persistent" | "ephemeral";
+
+export type AdapterSkillState =
+  | "available"
+  | "configured"
+  | "installed"
+  | "missing"
+  | "stale"
+  | "external";
+
+export interface AdapterSkillEntry {
+  name: string;
+  desired: boolean;
+  managed: boolean;
+  state: AdapterSkillState;
+  sourcePath?: string | null;
+  targetPath?: string | null;
+  detail?: string | null;
+}
+
+export interface AdapterSkillSnapshot {
+  adapterType: string;
+  supported: boolean;
+  mode: AdapterSkillSyncMode;
+  desiredSkills: string[];
+  entries: AdapterSkillEntry[];
+  warnings: string[];
+}
+
+export interface AdapterSkillContext {
+  agentId: string;
+  companyId: string;
+  adapterType: string;
+  config: Record<string, unknown>;
+}
+
 export interface AdapterEnvironmentTestContext {
   companyId: string;
   adapterType: string;
@@ -175,6 +211,8 @@ export interface ServerAdapterModule {
   type: string;
   execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult>;
   testEnvironment(ctx: AdapterEnvironmentTestContext): Promise<AdapterEnvironmentTestResult>;
+  listSkills?: (ctx: AdapterSkillContext) => Promise<AdapterSkillSnapshot>;
+  syncSkills?: (ctx: AdapterSkillContext, desiredSkills: string[]) => Promise<AdapterSkillSnapshot>;
   sessionCodec?: AdapterSessionCodec;
   supportsLocalAgentJwt?: boolean;
   models?: AdapterModel[];

packages/adapters/claude-local/src/server/execute.ts

@@ -12,6 +12,7 @@ import {
   parseObject,
   parseJson,
   buildPaperclipEnv,
+  listPaperclipSkillEntries,
   joinPromptSections,
   redactEnvForLogs,
   ensureAbsoluteDirectory,
@@ -27,40 +28,32 @@ import {
   isClaudeMaxTurnsResult,
   isClaudeUnknownSessionError,
 } from "./parse.js";
+import { resolveClaudeDesiredSkillNames } from "./skills.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
-const PAPERCLIP_SKILLS_CANDIDATES = [
-  path.resolve(__moduleDir, "../../skills"),         // published: <pkg>/dist/server/ -> <pkg>/skills/
-  path.resolve(__moduleDir, "../../../../../skills"), // dev: src/server/ -> repo root/skills/
-];
-
-async function resolvePaperclipSkillsDir(): Promise<string | null> {
-  for (const candidate of PAPERCLIP_SKILLS_CANDIDATES) {
-    const isDir = await fs.stat(candidate).then((s) => s.isDirectory()).catch(() => false);
-    if (isDir) return candidate;
-  }
-  return null;
-}
 
 /**
  * Create a tmpdir with `.claude/skills/` containing symlinks to skills from
  * the repo's `skills/` directory, so `--add-dir` makes Claude Code discover
  * them as proper registered skills.
  */
-async function buildSkillsDir(): Promise<string> {
+async function buildSkillsDir(config: Record<string, unknown>): Promise<string> {
   const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-skills-"));
   const target = path.join(tmp, ".claude", "skills");
   await fs.mkdir(target, { recursive: true });
-  const skillsDir = await resolvePaperclipSkillsDir();
-  if (!skillsDir) return tmp;
-  const entries = await fs.readdir(skillsDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (entry.isDirectory()) {
-      await fs.symlink(
-        path.join(skillsDir, entry.name),
-        path.join(target, entry.name),
-      );
-    }
+  const availableEntries = await listPaperclipSkillEntries(__moduleDir);
+  const desiredNames = new Set(
+    resolveClaudeDesiredSkillNames(
+      config,
+      availableEntries.map((entry) => entry.name),
+    ),
+  );
+  for (const entry of availableEntries) {
+    if (!desiredNames.has(entry.name)) continue;
+    await fs.symlink(
+      entry.source,
+      path.join(target, entry.name),
+    );
   }
   return tmp;
 }
@@ -337,7 +330,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     extraArgs,
   } = runtimeConfig;
   const billingType = resolveClaudeBillingType(env);
-  const skillsDir = await buildSkillsDir();
+  const skillsDir = await buildSkillsDir(config);
 
   // When instructionsFilePath is configured, create a combined temp file that
   // includes both the file content and the path directive, so we only need

packages/adapters/claude-local/src/server/index.ts

@@ -1,4 +1,5 @@
 export { execute, runClaudeLogin } from "./execute.js";
+export { listClaudeSkills, syncClaudeSkills } from "./skills.js";
 export { testEnvironment } from "./test.js";
 export {
   parseClaudeStreamJson,

packages/adapters/claude-local/src/server/skills.ts

@@ -0,0 +1,83 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  AdapterSkillContext,
+  AdapterSkillEntry,
+  AdapterSkillSnapshot,
+} from "@paperclipai/adapter-utils";
+import {
+  listPaperclipSkillEntries,
+  readPaperclipSkillSyncPreference,
+} from "@paperclipai/adapter-utils/server-utils";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+function resolveDesiredSkillNames(config: Record<string, unknown>, availableSkillNames: string[]) {
+  const preference = readPaperclipSkillSyncPreference(config);
+  return preference.explicit ? preference.desiredSkills : availableSkillNames;
+}
+
+async function buildClaudeSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
+  const availableEntries = await listPaperclipSkillEntries(__moduleDir);
+  const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
+  const desiredSkills = resolveDesiredSkillNames(
+    config,
+    availableEntries.map((entry) => entry.name),
+  );
+  const desiredSet = new Set(desiredSkills);
+  const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
+    name: entry.name,
+    desired: desiredSet.has(entry.name),
+    managed: true,
+    state: desiredSet.has(entry.name) ? "configured" : "available",
+    sourcePath: entry.source,
+    targetPath: null,
+    detail: desiredSet.has(entry.name)
+      ? "Will be mounted into the ephemeral Claude skill directory on the next run."
+      : null,
+  }));
+  const warnings: string[] = [];
+
+  for (const desiredSkill of desiredSkills) {
+    if (availableByName.has(desiredSkill)) continue;
+    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
+    entries.push({
+      name: desiredSkill,
+      desired: true,
+      managed: true,
+      state: "missing",
+      sourcePath: undefined,
+      targetPath: undefined,
+      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
+    });
+  }
+
+  entries.sort((left, right) => left.name.localeCompare(right.name));
+
+  return {
+    adapterType: "claude_local",
+    supported: true,
+    mode: "ephemeral",
+    desiredSkills,
+    entries,
+    warnings,
+  };
+}
+
+export async function listClaudeSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
+  return buildClaudeSkillSnapshot(ctx.config);
+}
+
+export async function syncClaudeSkills(
+  ctx: AdapterSkillContext,
+  _desiredSkills: string[],
+): Promise<AdapterSkillSnapshot> {
+  return buildClaudeSkillSnapshot(ctx.config);
+}
+
+export function resolveClaudeDesiredSkillNames(
+  config: Record<string, unknown>,
+  availableSkillNames: string[],
+) {
+  return resolveDesiredSkillNames(config, availableSkillNames);
+}

packages/adapters/codex-local/src/server/execute.ts

@@ -22,6 +22,7 @@ import {
 } from "@paperclipai/adapter-utils/server-utils";
 import { parseCodexJsonl, isCodexUnknownSessionError } from "./parse.js";
 import { pathExists, prepareWorktreeCodexHome, resolveCodexHomeDir } from "./codex-home.js";
+import { resolveCodexDesiredSkillNames } from "./skills.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
 const CODEX_ROLLOUT_NOISE_RE =
@@ -92,6 +93,7 @@ async function isLikelyPaperclipRuntimeSkillSource(candidate: string, skillName:
 type EnsureCodexSkillsInjectedOptions = {
   skillsHome?: string;
   skillsEntries?: Awaited<ReturnType<typeof listPaperclipSkillEntries>>;
+  desiredSkillNames?: string[];
   linkSkill?: (source: string, target: string) => Promise<void>;
 };
 
@@ -99,7 +101,11 @@ export async function ensureCodexSkillsInjected(
   onLog: AdapterExecutionContext["onLog"],
   options: EnsureCodexSkillsInjectedOptions = {},
 ) {
-  const skillsEntries = options.skillsEntries ?? await listPaperclipSkillEntries(__moduleDir);
+  const allSkillsEntries = options.skillsEntries ?? await listPaperclipSkillEntries(__moduleDir);
+  const desiredSkillNames =
+    options.desiredSkillNames ?? allSkillsEntries.map((entry) => entry.name);
+  const desiredSet = new Set(desiredSkillNames);
+  const skillsEntries = allSkillsEntries.filter((entry) => desiredSet.has(entry.name));
   if (skillsEntries.length === 0) return;
 
   const skillsHome = options.skillsHome ?? path.join(resolveCodexHomeDir(process.env), "skills");
@@ -213,13 +219,22 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     typeof envConfig.CODEX_HOME === "string" && envConfig.CODEX_HOME.trim().length > 0
       ? path.resolve(envConfig.CODEX_HOME.trim())
       : null;
+  const desiredSkillNames = resolveCodexDesiredSkillNames(
+    config,
+    (await listPaperclipSkillEntries(__moduleDir)).map((entry) => entry.name),
+  );
   await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
   const preparedWorktreeCodexHome =
     configuredCodexHome ? null : await prepareWorktreeCodexHome(process.env, onLog);
   const effectiveCodexHome = configuredCodexHome ?? preparedWorktreeCodexHome;
   await ensureCodexSkillsInjected(
     onLog,
-    effectiveCodexHome ? { skillsHome: path.join(effectiveCodexHome, "skills") } : {},
+    effectiveCodexHome
+      ? {
+          skillsHome: path.join(effectiveCodexHome, "skills"),
+          desiredSkillNames,
+        }
+      : { desiredSkillNames },
   );
   const hasExplicitApiKey =
     typeof envConfig.PAPERCLIP_API_KEY === "string" && envConfig.PAPERCLIP_API_KEY.trim().length > 0;

packages/adapters/codex-local/src/server/index.ts

@@ -1,4 +1,5 @@
 export { execute, ensureCodexSkillsInjected } from "./execute.js";
+export { listCodexSkills, syncCodexSkills } from "./skills.js";
 export { testEnvironment } from "./test.js";
 export { parseCodexJsonl, isCodexUnknownSessionError } from "./parse.js";
 import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";

packages/adapters/codex-local/src/server/skills.ts

@@ -0,0 +1,179 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  AdapterSkillContext,
+  AdapterSkillEntry,
+  AdapterSkillSnapshot,
+} from "@paperclipai/adapter-utils";
+import {
+  ensurePaperclipSkillSymlink,
+  listPaperclipSkillEntries,
+  readPaperclipSkillSyncPreference,
+} from "@paperclipai/adapter-utils/server-utils";
+import { resolveCodexHomeDir } from "./codex-home.js";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function resolveCodexSkillsHome(config: Record<string, unknown>) {
+  const env =
+    typeof config.env === "object" && config.env !== null && !Array.isArray(config.env)
+      ? (config.env as Record<string, unknown>)
+      : {};
+  const configuredCodexHome = asString(env.CODEX_HOME);
+  const home = configuredCodexHome ? path.resolve(configuredCodexHome) : resolveCodexHomeDir(process.env);
+  return path.join(home, "skills");
+}
+
+function resolveDesiredSkillNames(config: Record<string, unknown>, availableSkillNames: string[]) {
+  const preference = readPaperclipSkillSyncPreference(config);
+  return preference.explicit ? preference.desiredSkills : availableSkillNames;
+}
+
+async function readInstalledSkillTargets(skillsHome: string) {
+  const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
+  const out = new Map<string, { targetPath: string | null; kind: "symlink" | "directory" | "file" }>();
+  for (const entry of entries) {
+    const fullPath = path.join(skillsHome, entry.name);
+    if (entry.isSymbolicLink()) {
+      const linkedPath = await fs.readlink(fullPath).catch(() => null);
+      out.set(entry.name, {
+        targetPath: linkedPath ? path.resolve(path.dirname(fullPath), linkedPath) : null,
+        kind: "symlink",
+      });
+      continue;
+    }
+    if (entry.isDirectory()) {
+      out.set(entry.name, { targetPath: fullPath, kind: "directory" });
+      continue;
+    }
+    out.set(entry.name, { targetPath: fullPath, kind: "file" });
+  }
+  return out;
+}
+
+async function buildCodexSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
+  const availableEntries = await listPaperclipSkillEntries(__moduleDir);
+  const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
+  const desiredSkills = resolveDesiredSkillNames(
+    config,
+    availableEntries.map((entry) => entry.name),
+  );
+  const desiredSet = new Set(desiredSkills);
+  const skillsHome = resolveCodexSkillsHome(config);
+  const installed = await readInstalledSkillTargets(skillsHome);
+  const entries: AdapterSkillEntry[] = [];
+  const warnings: string[] = [];
+
+  for (const available of availableEntries) {
+    const installedEntry = installed.get(available.name) ?? null;
+    const desired = desiredSet.has(available.name);
+    let state: AdapterSkillEntry["state"] = "available";
+    let managed = false;
+    let detail: string | null = null;
+
+    if (installedEntry?.targetPath === available.source) {
+      managed = true;
+      state = desired ? "installed" : "stale";
+    } else if (installedEntry) {
+      state = "external";
+      detail = desired
+        ? "Skill name is occupied by an external installation."
+        : "Installed outside Paperclip management.";
+    } else if (desired) {
+      state = "missing";
+      detail = "Configured but not currently linked into the Codex skills home.";
+    }
+
+    entries.push({
+      name: available.name,
+      desired,
+      managed,
+      state,
+      sourcePath: available.source,
+      targetPath: path.join(skillsHome, available.name),
+      detail,
+    });
+  }
+
+  for (const desiredSkill of desiredSkills) {
+    if (availableByName.has(desiredSkill)) continue;
+    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
+    entries.push({
+      name: desiredSkill,
+      desired: true,
+      managed: true,
+      state: "missing",
+      sourcePath: null,
+      targetPath: path.join(skillsHome, desiredSkill),
+      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
+    });
+  }
+
+  for (const [name, installedEntry] of installed.entries()) {
+    if (availableByName.has(name)) continue;
+    entries.push({
+      name,
+      desired: false,
+      managed: false,
+      state: "external",
+      sourcePath: null,
+      targetPath: installedEntry.targetPath ?? path.join(skillsHome, name),
+      detail: "Installed outside Paperclip management.",
+    });
+  }
+
+  entries.sort((left, right) => left.name.localeCompare(right.name));
+
+  return {
+    adapterType: "codex_local",
+    supported: true,
+    mode: "persistent",
+    desiredSkills,
+    entries,
+    warnings,
+  };
+}
+
+export async function listCodexSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
+  return buildCodexSkillSnapshot(ctx.config);
+}
+
+export async function syncCodexSkills(
+  ctx: AdapterSkillContext,
+  desiredSkills: string[],
+): Promise<AdapterSkillSnapshot> {
+  const availableEntries = await listPaperclipSkillEntries(__moduleDir);
+  const desiredSet = new Set(desiredSkills);
+  const skillsHome = resolveCodexSkillsHome(ctx.config);
+  await fs.mkdir(skillsHome, { recursive: true });
+  const installed = await readInstalledSkillTargets(skillsHome);
+  const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
+
+  for (const available of availableEntries) {
+    if (!desiredSet.has(available.name)) continue;
+    const target = path.join(skillsHome, available.name);
+    await ensurePaperclipSkillSymlink(available.source, target);
+  }
+
+  for (const [name, installedEntry] of installed.entries()) {
+    const available = availableByName.get(name);
+    if (!available) continue;
+    if (desiredSet.has(name)) continue;
+    if (installedEntry.targetPath !== available.source) continue;
+    await fs.unlink(path.join(skillsHome, name)).catch(() => {});
+  }
+
+  return buildCodexSkillSnapshot(ctx.config);
+}
+
+export function resolveCodexDesiredSkillNames(
+  config: Record<string, unknown>,
+  availableSkillNames: string[],
+) {
+  return resolveDesiredSkillNames(config, availableSkillNames);
+}

packages/shared/src/index.ts

@@ -65,6 +65,11 @@ export {
 
 export type {
   Company,
+  AgentSkillSyncMode,
+  AgentSkillState,
+  AgentSkillEntry,
+  AgentSkillSnapshot,
+  AgentSkillSyncRequest,
   Agent,
   AgentPermissions,
   AgentKeyCreated,
@@ -136,6 +141,12 @@ export {
   updateCompanySchema,
   type CreateCompany,
   type UpdateCompany,
+  agentSkillStateSchema,
+  agentSkillSyncModeSchema,
+  agentSkillEntrySchema,
+  agentSkillSnapshotSchema,
+  agentSkillSyncSchema,
+  type AgentSkillSync,
   createAgentSchema,
   createAgentHireSchema,
   updateAgentSchema,

packages/shared/src/types/adapter-skills.ts

@@ -0,0 +1,32 @@
+export type AgentSkillSyncMode = "unsupported" | "persistent" | "ephemeral";
+
+export type AgentSkillState =
+  | "available"
+  | "configured"
+  | "installed"
+  | "missing"
+  | "stale"
+  | "external";
+
+export interface AgentSkillEntry {
+  name: string;
+  desired: boolean;
+  managed: boolean;
+  state: AgentSkillState;
+  sourcePath?: string | null;
+  targetPath?: string | null;
+  detail?: string | null;
+}
+
+export interface AgentSkillSnapshot {
+  adapterType: string;
+  supported: boolean;
+  mode: AgentSkillSyncMode;
+  desiredSkills: string[];
+  entries: AgentSkillEntry[];
+  warnings: string[];
+}
+
+export interface AgentSkillSyncRequest {
+  desiredSkills: string[];
+}

packages/shared/src/types/index.ts

@@ -1,4 +1,11 @@
 export type { Company } from "./company.js";
+export type {
+  AgentSkillSyncMode,
+  AgentSkillState,
+  AgentSkillEntry,
+  AgentSkillSnapshot,
+  AgentSkillSyncRequest,
+} from "./adapter-skills.js";
 export type {
   Agent,
   AgentPermissions,

packages/shared/src/validators/adapter-skills.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+
+export const agentSkillStateSchema = z.enum([
+  "available",
+  "configured",
+  "installed",
+  "missing",
+  "stale",
+  "external",
+]);
+
+export const agentSkillSyncModeSchema = z.enum([
+  "unsupported",
+  "persistent",
+  "ephemeral",
+]);
+
+export const agentSkillEntrySchema = z.object({
+  name: z.string().min(1),
+  desired: z.boolean(),
+  managed: z.boolean(),
+  state: agentSkillStateSchema,
+  sourcePath: z.string().nullable().optional(),
+  targetPath: z.string().nullable().optional(),
+  detail: z.string().nullable().optional(),
+});
+
+export const agentSkillSnapshotSchema = z.object({
+  adapterType: z.string().min(1),
+  supported: z.boolean(),
+  mode: agentSkillSyncModeSchema,
+  desiredSkills: z.array(z.string().min(1)),
+  entries: z.array(agentSkillEntrySchema),
+  warnings: z.array(z.string()),
+});
+
+export const agentSkillSyncSchema = z.object({
+  desiredSkills: z.array(z.string().min(1)),
+});
+
+export type AgentSkillSync = z.infer<typeof agentSkillSyncSchema>;

packages/shared/src/validators/index.ts

@@ -4,6 +4,14 @@ export {
   type CreateCompany,
   type UpdateCompany,
 } from "./company.js";
+export {
+  agentSkillStateSchema,
+  agentSkillSyncModeSchema,
+  agentSkillEntrySchema,
+  agentSkillSnapshotSchema,
+  agentSkillSyncSchema,
+  type AgentSkillSync,
+} from "./adapter-skills.js";
 export {
   portabilityIncludeSchema,
   portabilitySecretRequirementSchema,