The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Add adapter skill sync for codex and claude
Dotta56a34a8f8a2a
diff --git a/packages/adapter-utils/src/index.ts b/packages/adapter-utils/src/index.tsindex 56579022b0..c3dab36f87 100644--- a/packages/adapter-utils/src/index.ts+++ b/packages/adapter-utils/src/index.ts@@ -12,6 +12,11 @@ export type {AdapterEnvironmentTestStatus,AdapterEnvironmentTestResult,AdapterEnvironmentTestContext,+ AdapterSkillSyncMode,+ AdapterSkillState,+ AdapterSkillEntry,+ AdapterSkillSnapshot,+ AdapterSkillContext,AdapterSessionCodec,AdapterModel,HireApprovedPayload,diff --git a/packages/adapter-utils/src/server-utils.ts b/packages/adapter-utils/src/server-utils.tsindex 52e52b4c54..2648e4a8d8 100644--- a/packages/adapter-utils/src/server-utils.ts+++ b/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,diff --git a/packages/adapter-utils/src/types.ts b/packages/adapter-utils/src/types.tsindex df0d075a19..52afdb667e 100644--- a/packages/adapter-utils/src/types.ts+++ b/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[];diff --git a/packages/adapters/claude-local/src/server/execute.ts b/packages/adapters/claude-local/src/server/execute.tsindex 13d92df80e..8613191298 100644--- a/packages/adapters/claude-local/src/server/execute.ts+++ b/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<AdapterExecextraArgs,} = 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 needdiff --git a/packages/adapters/claude-local/src/server/index.ts b/packages/adapters/claude-local/src/server/index.tsindex 6b4ccb3e23..cb00dc5be1 100644--- a/packages/adapters/claude-local/src/server/index.ts+++ b/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,diff --git a/packages/adapters/claude-local/src/server/skills.ts b/packages/adapters/claude-local/src/server/skills.tsnew file mode 100644index 0000000000..b2c02501dc--- /dev/null+++ b/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);+}diff --git a/packages/adapters/codex-local/src/server/execute.ts b/packages/adapters/codex-local/src/server/execute.tsindex d4b3da464f..479126f0b7 100644--- a/packages/adapters/codex-local/src/server/execute.ts+++ b/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<AdapterExectypeof 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;diff --git a/packages/adapters/codex-local/src/server/index.ts b/packages/adapters/codex-local/src/server/index.tsindex 04c1e3685b..bbae3fb453 100644--- a/packages/adapters/codex-local/src/server/index.ts+++ b/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";diff --git a/packages/adapters/codex-local/src/server/skills.ts b/packages/adapters/codex-local/src/server/skills.tsnew file mode 100644index 0000000000..12e303479c--- /dev/null+++ b/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);+}diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.tsindex 1a222f2778..04c2e33b67 100644--- a/packages/shared/src/index.ts+++ b/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,diff --git a/packages/shared/src/types/adapter-skills.ts b/packages/shared/src/types/adapter-skills.tsnew file mode 100644index 0000000000..750ebaa4eb--- /dev/null+++ b/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[];+}diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.tsindex 07862c581e..9404fca3b4 100644--- a/packages/shared/src/types/index.ts+++ b/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,diff --git a/packages/shared/src/validators/adapter-skills.ts b/packages/shared/src/validators/adapter-skills.tsnew file mode 100644index 0000000000..07a71de505--- /dev/null+++ b/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>;diff --git a/packages/shared/src/validators/index.ts b/packages/shared/src/validators/index.tsindex ad74a1e870..e432510bb7 100644--- a/packages/shared/src/validators/index.ts+++ b/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,diff --git a/server/src/__tests__/claude-local-skill-sync.test.ts b/server/src/__tests__/claude-local-skill-sync.test.tsnew file mode 100644index 0000000000..5a6f13e2bc--- /dev/null+++ b/server/src/__tests__/claude-local-skill-sync.test.ts@@ -0,0 +1,38 @@+import { describe, expect, it } from "vitest";+import {+ listClaudeSkills,+ syncClaudeSkills,+} from "@paperclipai/adapter-claude-local/server";++describe("claude local skill sync", () => {+ it("defaults to mounting all built-in Paperclip skills when no explicit selection exists", async () => {+ const snapshot = await listClaudeSkills({+ agentId: "agent-1",+ companyId: "company-1",+ adapterType: "claude_local",+ config: {},+ });++ expect(snapshot.mode).toBe("ephemeral");+ expect(snapshot.supported).toBe(true);+ expect(snapshot.desiredSkills).toContain("paperclip");+ expect(snapshot.entries.find((entry) => entry.name === "paperclip")?.state).toBe("configured");+ });++ it("respects an explicit desired skill list without mutating a persistent home", async () => {+ const snapshot = await syncClaudeSkills({+ agentId: "agent-2",+ companyId: "company-1",+ adapterType: "claude_local",+ config: {+ paperclipSkillSync: {+ desiredSkills: ["paperclip"],+ },+ },+ }, ["paperclip"]);++ expect(snapshot.desiredSkills).toEqual(["paperclip"]);+ expect(snapshot.entries.find((entry) => entry.name === "paperclip")?.state).toBe("configured");+ expect(snapshot.entries.find((entry) => entry.name === "paperclip-create-agent")?.state).toBe("available");+ });+});diff --git a/server/src/__tests__/codex-local-skill-sync.test.ts b/server/src/__tests__/codex-local-skill-sync.test.tsnew file mode 100644index 0000000000..79c1d89581--- /dev/null+++ b/server/src/__tests__/codex-local-skill-sync.test.ts@@ -0,0 +1,87 @@+import fs from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { afterEach, describe, expect, it } from "vitest";+import {+ listCodexSkills,+ syncCodexSkills,+} from "@paperclipai/adapter-codex-local/server";++async function makeTempDir(prefix: string): Promise<string> {+ return fs.mkdtemp(path.join(os.tmpdir(), prefix));+}++describe("codex local skill sync", () => {+ const cleanupDirs = new Set<string>();++ afterEach(async () => {+ await Promise.all(Array.from(cleanupDirs).map((dir) => fs.rm(dir, { recursive: true, force: true })));+ cleanupDirs.clear();+ });++ it("reports configured Paperclip skills and installs them into the Codex skills home", async () => {+ const codexHome = await makeTempDir("paperclip-codex-skill-sync-");+ cleanupDirs.add(codexHome);++ const ctx = {+ agentId: "agent-1",+ companyId: "company-1",+ adapterType: "codex_local",+ config: {+ env: {+ CODEX_HOME: codexHome,+ },+ paperclipSkillSync: {+ desiredSkills: ["paperclip"],+ },+ },+ } as const;++ const before = await listCodexSkills(ctx);+ expect(before.mode).toBe("persistent");+ expect(before.desiredSkills).toEqual(["paperclip"]);+ expect(before.entries.find((entry) => entry.name === "paperclip")?.state).toBe("missing");++ const after = await syncCodexSkills(ctx, ["paperclip"]);+ expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");+ expect((await fs.lstat(path.join(codexHome, "skills", "paperclip"))).isSymbolicLink()).toBe(true);+ });++ it("removes stale managed Paperclip skills when the desired set is emptied", async () => {+ const codexHome = await makeTempDir("paperclip-codex-skill-prune-");+ cleanupDirs.add(codexHome);++ const configuredCtx = {+ agentId: "agent-2",+ companyId: "company-1",+ adapterType: "codex_local",+ config: {+ env: {+ CODEX_HOME: codexHome,+ },+ paperclipSkillSync: {+ desiredSkills: ["paperclip"],+ },+ },+ } as const;++ await syncCodexSkills(configuredCtx, ["paperclip"]);++ const clearedCtx = {+ ...configuredCtx,+ config: {+ env: {+ CODEX_HOME: codexHome,+ },+ paperclipSkillSync: {+ desiredSkills: [],+ },+ },+ } as const;++ const after = await syncCodexSkills(clearedCtx, []);+ expect(after.desiredSkills).toEqual([]);+ expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("available");+ await expect(fs.lstat(path.join(codexHome, "skills", "paperclip"))).rejects.toThrow();+ });+});diff --git a/server/src/adapters/registry.ts b/server/src/adapters/registry.tsindex 14cdf6d9b0..d5914b4d32 100644--- a/server/src/adapters/registry.ts+++ b/server/src/adapters/registry.ts@@ -1,12 +1,16 @@import type { ServerAdapterModule } from "./types.js";import {execute as claudeExecute,+ listClaudeSkills,+ syncClaudeSkills,testEnvironment as claudeTestEnvironment,sessionCodec as claudeSessionCodec,} from "@paperclipai/adapter-claude-local/server";import { agentConfigurationDoc as claudeAgentConfigurationDoc, models as claudeModels } from "@paperclipai/adapter-claude-local";import {execute as codexExecute,+ listCodexSkills,+ syncCodexSkills,testEnvironment as codexTestEnvironment,sessionCodec as codexSessionCodec,} from "@paperclipai/adapter-codex-local/server";@@ -58,6 +62,8 @@ const claudeLocalAdapter: ServerAdapterModule = {type: "claude_local",execute: claudeExecute,testEnvironment: claudeTestEnvironment,+ listSkills: listClaudeSkills,+ syncSkills: syncClaudeSkills,sessionCodec: claudeSessionCodec,models: claudeModels,supportsLocalAgentJwt: true,@@ -68,6 +74,8 @@ const codexLocalAdapter: ServerAdapterModule = {type: "codex_local",execute: codexExecute,testEnvironment: codexTestEnvironment,+ listSkills: listCodexSkills,+ syncSkills: syncCodexSkills,sessionCodec: codexSessionCodec,models: codexModels,listModels: listCodexModels,diff --git a/server/src/adapters/types.ts b/server/src/adapters/types.tsindex c5708d8a5f..a43a4f54c7 100644--- a/server/src/adapters/types.ts+++ b/server/src/adapters/types.ts@@ -13,6 +13,11 @@ export type {AdapterEnvironmentTestStatus,AdapterEnvironmentTestResult,AdapterEnvironmentTestContext,+ AdapterSkillSyncMode,+ AdapterSkillState,+ AdapterSkillEntry,+ AdapterSkillSnapshot,+ AdapterSkillContext,AdapterSessionCodec,AdapterModel,ServerAdapterModule,diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.tsindex 6c60b64484..9e429df644 100644--- a/server/src/routes/agents.ts+++ b/server/src/routes/agents.ts@@ -5,6 +5,7 @@ import type { Db } from "@paperclipai/db";import { agents as agentsTable, companies, heartbeatRuns } from "@paperclipai/db";import { and, desc, eq, inArray, not, sql } from "drizzle-orm";import {+ agentSkillSyncSchema,createAgentKeySchema,createAgentHireSchema,createAgentSchema,@@ -12,12 +13,17 @@ import {isUuidLike,resetAgentSessionSchema,testAdapterEnvironmentSchema,+ type AgentSkillSnapshot,type InstanceSchedulerHeartbeatAgent,updateAgentPermissionsSchema,updateAgentInstructionsPathSchema,wakeAgentSchema,updateAgentSchema,} from "@paperclipai/shared";+import {+ readPaperclipSkillSyncPreference,+ writePaperclipSkillSyncPreference,+} from "@paperclipai/adapter-utils/server-utils";import { validate } from "../middleware/validate.js";import {agentService,@@ -334,6 +340,20 @@ export function agentRoutes(db: Db) {return details;}+ function buildUnsupportedSkillSnapshot(+ adapterType: string,+ desiredSkills: string[] = [],+ ): AgentSkillSnapshot {+ return {+ adapterType,+ supported: false,+ mode: "unsupported",+ desiredSkills,+ entries: [],+ warnings: ["This adapter does not implement skill sync yet."],+ };+ }+function redactForRestrictedAgentView(agent: Awaited<ReturnType<typeof svc.getById>>) {if (!agent) return null;return {@@ -459,6 +479,119 @@ export function agentRoutes(db: Db) {},);+ router.get("/agents/:id/skills", async (req, res) => {+ const id = req.params.id as string;+ const agent = await svc.getById(id);+ if (!agent) {+ res.status(404).json({ error: "Agent not found" });+ return;+ }+ await assertCanReadConfigurations(req, agent.companyId);++ const adapter = findServerAdapter(agent.adapterType);+ if (!adapter?.listSkills) {+ const preference = readPaperclipSkillSyncPreference(+ agent.adapterConfig as Record<string, unknown>,+ );+ res.json(buildUnsupportedSkillSnapshot(agent.adapterType, preference.desiredSkills));+ return;+ }++ const { config: runtimeConfig } = await secretsSvc.resolveAdapterConfigForRuntime(+ agent.companyId,+ agent.adapterConfig,+ );+ const snapshot = await adapter.listSkills({+ agentId: agent.id,+ companyId: agent.companyId,+ adapterType: agent.adapterType,+ config: runtimeConfig,+ });+ res.json(snapshot);+ });++ router.post(+ "/agents/:id/skills/sync",+ validate(agentSkillSyncSchema),+ async (req, res) => {+ const id = req.params.id as string;+ const agent = await svc.getById(id);+ if (!agent) {+ res.status(404).json({ error: "Agent not found" });+ return;+ }+ await assertCanUpdateAgent(req, agent);++ const desiredSkills = Array.from(+ new Set(+ (req.body.desiredSkills as string[])+ .map((value) => value.trim())+ .filter(Boolean),+ ),+ );+ const nextAdapterConfig = writePaperclipSkillSyncPreference(+ agent.adapterConfig as Record<string, unknown>,+ desiredSkills,+ );+ const actor = getActorInfo(req);+ const updated = await svc.update(agent.id, {+ adapterConfig: nextAdapterConfig,+ }, {+ recordRevision: {+ createdByAgentId: actor.agentId,+ createdByUserId: actor.actorType === "user" ? actor.actorId : null,+ source: "skill-sync",+ },+ });+ if (!updated) {+ res.status(404).json({ error: "Agent not found" });+ return;+ }++ const adapter = findServerAdapter(updated.adapterType);+ const { config: runtimeConfig } = await secretsSvc.resolveAdapterConfigForRuntime(+ updated.companyId,+ updated.adapterConfig,+ );+ const snapshot = adapter?.syncSkills+ ? await adapter.syncSkills({+ agentId: updated.id,+ companyId: updated.companyId,+ adapterType: updated.adapterType,+ config: runtimeConfig,+ }, desiredSkills)+ : adapter?.listSkills+ ? await adapter.listSkills({+ agentId: updated.id,+ companyId: updated.companyId,+ adapterType: updated.adapterType,+ config: runtimeConfig,+ })+ : buildUnsupportedSkillSnapshot(updated.adapterType, desiredSkills);++ await logActivity(db, {+ companyId: updated.companyId,+ actorType: actor.actorType,+ actorId: actor.actorId,+ action: "agent.skills_synced",+ entityType: "agent",+ entityId: updated.id,+ agentId: actor.agentId,+ runId: actor.runId,+ details: {+ adapterType: updated.adapterType,+ desiredSkills,+ mode: snapshot.mode,+ supported: snapshot.supported,+ entryCount: snapshot.entries.length,+ warningCount: snapshot.warnings.length,+ },+ });++ res.json(snapshot);+ },+ );+router.get("/companies/:companyId/agents", async (req, res) => {const companyId = req.params.companyId as string;assertCompanyAccess(req, companyId);diff --git a/ui/src/api/agents.ts b/ui/src/api/agents.tsindex 85486af988..cb2d61b8d8 100644--- a/ui/src/api/agents.ts+++ b/ui/src/api/agents.ts@@ -1,5 +1,6 @@import type {Agent,+ AgentSkillSnapshot,AdapterEnvironmentTestResult,AgentKeyCreated,AgentRuntimeState,@@ -107,6 +108,10 @@ export const agentsApi = {terminate: (id: string, companyId?: string) => api.post<Agent>(agentPath(id, companyId, "/terminate"), {}),remove: (id: string, companyId?: string) => api.delete<{ ok: true }>(agentPath(id, companyId)),listKeys: (id: string, companyId?: string) => api.get<AgentKey[]>(agentPath(id, companyId, "/keys")),+ skills: (id: string, companyId?: string) =>+ api.get<AgentSkillSnapshot>(agentPath(id, companyId, "/skills")),+ syncSkills: (id: string, desiredSkills: string[], companyId?: string) =>+ api.post<AgentSkillSnapshot>(agentPath(id, companyId, "/skills/sync"), { desiredSkills }),createKey: (id: string, name: string, companyId?: string) =>api.post<AgentKeyCreated>(agentPath(id, companyId, "/keys"), { name }),revokeKey: (agentId: string, keyId: string, companyId?: string) =>diff --git a/ui/src/lib/queryKeys.ts b/ui/src/lib/queryKeys.tsindex c500afdc5f..b1da418dd9 100644--- a/ui/src/lib/queryKeys.ts+++ b/ui/src/lib/queryKeys.ts@@ -9,6 +9,7 @@ export const queryKeys = {detail: (id: string) => ["agents", "detail", id] as const,runtimeState: (id: string) => ["agents", "runtime-state", id] as const,taskSessions: (id: string) => ["agents", "task-sessions", id] as const,+ skills: (id: string) => ["agents", "skills", id] as const,keys: (agentId: string) => ["agents", "keys", agentId] as const,configRevisions: (agentId: string) => ["agents", "config-revisions", agentId] as const,adapterModels: (companyId: string, adapterType: string) =>diff --git a/ui/src/pages/AgentDetail.tsx b/ui/src/pages/AgentDetail.tsxindex 3092180776..f2086ee8e9 100644--- a/ui/src/pages/AgentDetail.tsx+++ b/ui/src/pages/AgentDetail.tsx@@ -1045,6 +1045,8 @@ function ConfigurationTab({}) {const queryClient = useQueryClient();const [awaitingRefreshAfterSave, setAwaitingRefreshAfterSave] = useState(false);+ const [skillDraft, setSkillDraft] = useState<string[]>([]);+ const [skillDirty, setSkillDirty] = useState(false);const lastAgentRef = useRef(agent);const { data: adapterModels } = useQuery({@@ -1056,6 +1058,12 @@ function ConfigurationTab({enabled: Boolean(companyId),});+ const { data: skillSnapshot } = useQuery({+ queryKey: queryKeys.agents.skills(agent.id),+ queryFn: () => agentsApi.skills(agent.id, companyId),+ enabled: Boolean(companyId),+ });+const updateAgent = useMutation({mutationFn: (data: Record<string, unknown>) => agentsApi.update(agent.id, data, companyId),onMutate: () => {@@ -1071,6 +1079,17 @@ function ConfigurationTab({},});+ const syncSkills = useMutation({+ mutationFn: (desiredSkills: string[]) => agentsApi.syncSkills(agent.id, desiredSkills, companyId),+ onSuccess: (snapshot) => {+ queryClient.invalidateQueries({ queryKey: queryKeys.agents.detail(agent.id) });+ queryClient.invalidateQueries({ queryKey: queryKeys.agents.detail(agent.urlKey) });+ queryClient.invalidateQueries({ queryKey: queryKeys.agents.skills(agent.id) });+ setSkillDraft(snapshot.desiredSkills);+ setSkillDirty(false);+ },+ });+useEffect(() => {if (awaitingRefreshAfterSave && agent !== lastAgentRef.current) {setAwaitingRefreshAfterSave(false);@@ -1078,6 +1097,12 @@ function ConfigurationTab({lastAgentRef.current = agent;}, [agent, awaitingRefreshAfterSave]);+ useEffect(() => {+ if (!skillSnapshot) return;+ setSkillDraft(skillSnapshot.desiredSkills);+ setSkillDirty(false);+ }, [skillSnapshot]);+const isConfigSaving = updateAgent.isPending || awaitingRefreshAfterSave;useEffect(() => {@@ -1118,6 +1143,128 @@ function ConfigurationTab({</div></div></div>++ <div>+ <h3 className="text-sm font-medium mb-3">Skills</h3>+ <div className="border border-border rounded-lg p-4 space-y-3">+ {!skillSnapshot ? (+ <p className="text-sm text-muted-foreground">Loading skill sync state…</p>+ ) : !skillSnapshot.supported ? (+ <div className="space-y-2">+ <p className="text-sm text-muted-foreground">+ This adapter does not implement skill sync yet.+ </p>+ {skillSnapshot.warnings.map((warning) => (+ <p key={warning} className="text-xs text-muted-foreground">+ {warning}+ </p>+ ))}+ </div>+ ) : (+ <>+ <p className="text-sm text-muted-foreground">+ {skillSnapshot.mode === "persistent"+ ? "These skills are synced into the adapter's persistent skills home."+ : "These skills are mounted ephemerally for each Claude run."}+ </p>++ <div className="space-y-2">+ {skillSnapshot.entries+ .filter((entry) => entry.managed)+ .map((entry) => {+ const checked = skillDraft.includes(entry.name);+ return (+ <label+ key={entry.name}+ className="flex items-start gap-3 rounded-md border border-border/70 px-3 py-2"+ >+ <input+ type="checkbox"+ checked={checked}+ onChange={(e) => {+ const next = e.target.checked+ ? Array.from(new Set([...skillDraft, entry.name]))+ : skillDraft.filter((value) => value !== entry.name);+ setSkillDraft(next);+ setSkillDirty(true);+ }}+ />+ <div className="min-w-0 flex-1">+ <div className="flex items-center justify-between gap-2">+ <span className="text-sm font-medium">{entry.name}</span>+ <span className="rounded-full border border-border px-2 py-0.5 text-[10px] uppercase tracking-wide text-muted-foreground">+ {entry.state}+ </span>+ </div>+ {entry.detail && (+ <p className="mt-1 text-xs text-muted-foreground">+ {entry.detail}+ </p>+ )}+ </div>+ </label>+ );+ })}+ </div>++ {skillSnapshot.entries.some((entry) => entry.state === "external") && (+ <div className="space-y-1">+ <div className="text-xs uppercase tracking-wide text-muted-foreground">+ External skills+ </div>+ {skillSnapshot.entries+ .filter((entry) => entry.state === "external")+ .map((entry) => (+ <div key={entry.name} className="text-xs text-muted-foreground">+ {entry.name}+ {entry.detail ? ` - ${entry.detail}` : ""}+ </div>+ ))}+ </div>+ )}++ {skillSnapshot.warnings.length > 0 && (+ <div className="space-y-1 rounded-md border border-amber-300/60 bg-amber-50/60 px-3 py-2 text-xs text-amber-700">+ {skillSnapshot.warnings.map((warning) => (+ <div key={warning}>{warning}</div>+ ))}+ </div>+ )}++ {syncSkills.isError && (+ <p className="text-xs text-destructive">+ {syncSkills.error instanceof Error+ ? syncSkills.error.message+ : "Failed to sync skills"}+ </p>+ )}++ <div className="flex items-center gap-2">+ <Button+ size="sm"+ onClick={() => syncSkills.mutate(skillDraft)}+ disabled={syncSkills.isPending || !skillDirty}+ >+ {syncSkills.isPending ? "Syncing..." : "Sync skills"}+ </Button>+ {skillDirty && (+ <Button+ variant="ghost"+ size="sm"+ onClick={() => {+ setSkillDraft(skillSnapshot.desiredSkills);+ setSkillDirty(false);+ }}+ disabled={syncSkills.isPending}+ >+ Reset+ </Button>+ )}+ </div>+ </>+ )}+ </div>+ </div></div>);}