Skip to content

The open-source app everyone uses to manage agents at work

Fix runtime skill injection across adapters

Dotta7675fd0856be
diff --git a/packages/adapter-utils/src/server-utils.ts b/packages/adapter-utils/src/server-utils.ts
index 2648e4a8d8..1afe4c3bf3 100644
--- a/packages/adapter-utils/src/server-utils.ts
+++ b/packages/adapter-utils/src/server-utils.ts
@@ -40,6 +40,8 @@ const PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES = [
export interface PaperclipSkillEntry {
name: string;
source: string;
+ required?: boolean;
+ requiredReason?: string | null;
}
function normalizePathSlashes(value: string): string {
@@ -306,12 +308,45 @@ export async function listPaperclipSkillEntries(
.map((entry) => ({
name: entry.name,
source: path.join(root, entry.name),
+ required: true,
+ requiredReason: "Bundled Paperclip skills are always available for local adapters.",
}));
} catch {
return [];
}
}
+function normalizeConfiguredPaperclipRuntimeSkills(value: unknown): PaperclipSkillEntry[] {
+ if (!Array.isArray(value)) return [];
+ const out: PaperclipSkillEntry[] = [];
+ for (const rawEntry of value) {
+ const entry = parseObject(rawEntry);
+ const name = asString(entry.name, "").trim();
+ const source = asString(entry.source, "").trim();
+ if (!name || !source) continue;
+ out.push({
+ name,
+ source,
+ required: asBoolean(entry.required, false),
+ requiredReason:
+ typeof entry.requiredReason === "string" && entry.requiredReason.trim().length > 0
+ ? entry.requiredReason.trim()
+ : null,
+ });
+ }
+ return out;
+}
+
+export async function readPaperclipRuntimeSkillEntries(
+ config: Record<string, unknown>,
+ moduleDir: string,
+ additionalCandidates: string[] = [],
+): Promise<PaperclipSkillEntry[]> {
+ const configuredEntries = normalizeConfiguredPaperclipRuntimeSkills(config.paperclipRuntimeSkills);
+ if (configuredEntries.length > 0) return configuredEntries;
+ return listPaperclipSkillEntries(moduleDir, additionalCandidates);
+}
+
export async function readPaperclipSkillMarkdown(
moduleDir: string,
skillName: string,
@@ -352,6 +387,20 @@ export function readPaperclipSkillSyncPreference(config: Record<string, unknown>
};
}
+export function resolvePaperclipDesiredSkillNames(
+ config: Record<string, unknown>,
+ availableEntries: Array<{ name: string; required?: boolean }>,
+): string[] {
+ const preference = readPaperclipSkillSyncPreference(config);
+ const requiredSkills = availableEntries
+ .filter((entry) => entry.required)
+ .map((entry) => entry.name);
+ if (!preference.explicit) {
+ return Array.from(new Set(requiredSkills));
+ }
+ return Array.from(new Set([...requiredSkills, ...preference.desiredSkills]));
+}
+
export function writePaperclipSkillSyncPreference(
config: Record<string, unknown>,
desiredSkills: string[],
diff --git a/packages/adapter-utils/src/types.ts b/packages/adapter-utils/src/types.ts
index 52afdb667e..2619580428 100644
--- a/packages/adapter-utils/src/types.ts
+++ b/packages/adapter-utils/src/types.ts
@@ -152,6 +152,8 @@ export interface AdapterSkillEntry {
name: string;
desired: boolean;
managed: boolean;
+ required?: boolean;
+ requiredReason?: string | null;
state: AdapterSkillState;
sourcePath?: string | null;
targetPath?: string | null;
diff --git a/packages/adapters/claude-local/src/server/execute.ts b/packages/adapters/claude-local/src/server/execute.ts
index 86745e7fba..eb7d89e300 100644
--- a/packages/adapters/claude-local/src/server/execute.ts
+++ b/packages/adapters/claude-local/src/server/execute.ts
@@ -12,7 +12,7 @@ import {
parseObject,
parseJson,
buildPaperclipEnv,
- listPaperclipSkillEntries,
+ readPaperclipRuntimeSkillEntries,
joinPromptSections,
redactEnvForLogs,
ensureAbsoluteDirectory,
@@ -41,11 +41,11 @@ 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 availableEntries = await listPaperclipSkillEntries(__moduleDir);
+ const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const desiredNames = new Set(
resolveClaudeDesiredSkillNames(
config,
- availableEntries.map((entry) => entry.name),
+ availableEntries,
),
);
for (const entry of availableEntries) {
diff --git a/packages/adapters/claude-local/src/server/skills.ts b/packages/adapters/claude-local/src/server/skills.ts
index b2c02501dc..194ef3248b 100644
--- a/packages/adapters/claude-local/src/server/skills.ts
+++ b/packages/adapters/claude-local/src/server/skills.ts
@@ -6,24 +6,16 @@ import type {
AdapterSkillSnapshot,
} from "@paperclipai/adapter-utils";
import {
- listPaperclipSkillEntries,
- readPaperclipSkillSyncPreference,
+ readPaperclipRuntimeSkillEntries,
+ resolvePaperclipDesiredSkillNames,
} 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 availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
- const desiredSkills = resolveDesiredSkillNames(
- config,
- availableEntries.map((entry) => entry.name),
- );
+ const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
name: entry.name,
@@ -35,6 +27,8 @@ async function buildClaudeSkillSnapshot(config: Record<string, unknown>): Promis
detail: desiredSet.has(entry.name)
? "Will be mounted into the ephemeral Claude skill directory on the next run."
: null,
+ required: Boolean(entry.required),
+ requiredReason: entry.requiredReason ?? null,
}));
const warnings: string[] = [];
@@ -77,7 +71,7 @@ export async function syncClaudeSkills(
export function resolveClaudeDesiredSkillNames(
config: Record<string, unknown>,
- availableSkillNames: string[],
+ availableEntries: Array<{ name: string; required?: boolean }>,
) {
- return resolveDesiredSkillNames(config, availableSkillNames);
+ return resolvePaperclipDesiredSkillNames(config, availableEntries);
}
diff --git a/packages/adapters/codex-local/src/server/execute.ts b/packages/adapters/codex-local/src/server/execute.ts
index 452b8761e1..72972fa265 100644
--- a/packages/adapters/codex-local/src/server/execute.ts
+++ b/packages/adapters/codex-local/src/server/execute.ts
@@ -14,7 +14,8 @@ import {
ensureCommandResolvable,
ensurePaperclipSkillSymlink,
ensurePathInEnv,
- listPaperclipSkillEntries,
+ readPaperclipRuntimeSkillEntries,
+ resolvePaperclipDesiredSkillNames,
removeMaintainerOnlySkillSymlinks,
renderTemplate,
joinPromptSections,
@@ -92,7 +93,7 @@ async function isLikelyPaperclipRuntimeSkillSource(candidate: string, skillName:
type EnsureCodexSkillsInjectedOptions = {
skillsHome?: string;
- skillsEntries?: Awaited<ReturnType<typeof listPaperclipSkillEntries>>;
+ skillsEntries?: Array<{ name: string; source: string }>;
desiredSkillNames?: string[];
linkSkill?: (source: string, target: string) => Promise<void>;
};
@@ -101,7 +102,7 @@ export async function ensureCodexSkillsInjected(
onLog: AdapterExecutionContext["onLog"],
options: EnsureCodexSkillsInjectedOptions = {},
) {
- const allSkillsEntries = options.skillsEntries ?? await listPaperclipSkillEntries(__moduleDir);
+ const allSkillsEntries = options.skillsEntries ?? await readPaperclipRuntimeSkillEntries({}, __moduleDir);
const desiredSkillNames =
options.desiredSkillNames ?? allSkillsEntries.map((entry) => entry.name);
const desiredSet = new Set(desiredSkillNames);
@@ -220,10 +221,8 @@ 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),
- );
+ const codexSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+ const desiredSkillNames = resolveCodexDesiredSkillNames(config, codexSkillEntries);
await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
const preparedWorktreeCodexHome =
configuredCodexHome ? null : await prepareWorktreeCodexHome(process.env, onLog);
@@ -231,11 +230,12 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
await ensureCodexSkillsInjected(
onLog,
effectiveCodexHome
- ? {
+ ? {
skillsHome: path.join(effectiveCodexHome, "skills"),
+ skillsEntries: codexSkillEntries,
desiredSkillNames,
}
- : { desiredSkillNames },
+ : { skillsEntries: codexSkillEntries, 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/skills.ts b/packages/adapters/codex-local/src/server/skills.ts
index 12e303479c..b2fccab91b 100644
--- a/packages/adapters/codex-local/src/server/skills.ts
+++ b/packages/adapters/codex-local/src/server/skills.ts
@@ -8,8 +8,8 @@ import type {
} from "@paperclipai/adapter-utils";
import {
ensurePaperclipSkillSymlink,
- listPaperclipSkillEntries,
- readPaperclipSkillSyncPreference,
+ readPaperclipRuntimeSkillEntries,
+ resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
import { resolveCodexHomeDir } from "./codex-home.js";
@@ -29,11 +29,6 @@ function resolveCodexSkillsHome(config: Record<string, unknown>) {
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" }>();
@@ -57,12 +52,9 @@ async function readInstalledSkillTargets(skillsHome: string) {
}
async function buildCodexSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
- const availableEntries = await listPaperclipSkillEntries(__moduleDir);
+ const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
- const desiredSkills = resolveDesiredSkillNames(
- config,
- availableEntries.map((entry) => entry.name),
- );
+ const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveCodexSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
@@ -97,6 +89,8 @@ async function buildCodexSkillSnapshot(config: Record<string, unknown>): Promise
sourcePath: available.source,
targetPath: path.join(skillsHome, available.name),
detail,
+ required: Boolean(available.required),
+ requiredReason: available.requiredReason ?? null,
});
}
@@ -147,8 +141,11 @@ export async function syncCodexSkills(
ctx: AdapterSkillContext,
desiredSkills: string[],
): Promise<AdapterSkillSnapshot> {
- const availableEntries = await listPaperclipSkillEntries(__moduleDir);
- const desiredSet = new Set(desiredSkills);
+ const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
+ const desiredSet = new Set([
+ ...desiredSkills,
+ ...availableEntries.filter((entry) => entry.required).map((entry) => entry.name),
+ ]);
const skillsHome = resolveCodexSkillsHome(ctx.config);
await fs.mkdir(skillsHome, { recursive: true });
const installed = await readInstalledSkillTargets(skillsHome);
@@ -173,7 +170,7 @@ export async function syncCodexSkills(
export function resolveCodexDesiredSkillNames(
config: Record<string, unknown>,
- availableSkillNames: string[],
+ availableEntries: Array<{ name: string; required?: boolean }>,
) {
- return resolveDesiredSkillNames(config, availableSkillNames);
+ return resolvePaperclipDesiredSkillNames(config, availableEntries);
}
diff --git a/packages/adapters/cursor-local/src/server/execute.ts b/packages/adapters/cursor-local/src/server/execute.ts
index 52fe73f85d..daca09bcb3 100644
--- a/packages/adapters/cursor-local/src/server/execute.ts
+++ b/packages/adapters/cursor-local/src/server/execute.ts
@@ -14,8 +14,8 @@ import {
ensureCommandResolvable,
ensurePaperclipSkillSymlink,
ensurePathInEnv,
- listPaperclipSkillEntries,
- readPaperclipSkillSyncPreference,
+ readPaperclipRuntimeSkillEntries,
+ resolvePaperclipDesiredSkillNames,
removeMaintainerOnlySkillSymlinks,
renderTemplate,
joinPromptSections,
@@ -98,7 +98,7 @@ export async function ensureCursorSkillsInjected(
? (await fs.readdir(options.skillsDir, { withFileTypes: true }))
.filter((entry) => entry.isDirectory())
.map((entry) => ({ name: entry.name, source: path.join(options.skillsDir!, entry.name) }))
- : await listPaperclipSkillEntries(__moduleDir));
+ : await readPaperclipRuntimeSkillEntries({}, __moduleDir));
if (skillsEntries.length === 0) return;
const skillsHome = options.skillsHome ?? cursorSkillsHome();
@@ -169,11 +169,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
- const cursorSkillEntries = await listPaperclipSkillEntries(__moduleDir);
- const cursorPreference = readPaperclipSkillSyncPreference(config);
- const desiredCursorSkillNames = cursorPreference.explicit
- ? cursorPreference.desiredSkills
- : cursorSkillEntries.map((entry) => entry.name);
+ const cursorSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+ const desiredCursorSkillNames = resolvePaperclipDesiredSkillNames(config, cursorSkillEntries);
await ensureCursorSkillsInjected(onLog, {
skillsEntries: cursorSkillEntries.filter((entry) => desiredCursorSkillNames.includes(entry.name)),
});
diff --git a/packages/adapters/cursor-local/src/server/skills.ts b/packages/adapters/cursor-local/src/server/skills.ts
index c9d6d9459b..c05d1b20ca 100644
--- a/packages/adapters/cursor-local/src/server/skills.ts
+++ b/packages/adapters/cursor-local/src/server/skills.ts
@@ -9,8 +9,8 @@ import type {
} from "@paperclipai/adapter-utils";
import {
ensurePaperclipSkillSymlink,
- listPaperclipSkillEntries,
- readPaperclipSkillSyncPreference,
+ readPaperclipRuntimeSkillEntries,
+ resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
@@ -29,11 +29,6 @@ function resolveCursorSkillsHome(config: Record<string, unknown>) {
return path.join(home, ".cursor", "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" }>();
@@ -57,12 +52,9 @@ async function readInstalledSkillTargets(skillsHome: string) {
}
async function buildCursorSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
- const availableEntries = await listPaperclipSkillEntries(__moduleDir);
+ const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
- const desiredSkills = resolveDesiredSkillNames(
- config,
- availableEntries.map((entry) => entry.name),
- );
+ const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveCursorSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
@@ -97,6 +89,8 @@ async function buildCursorSkillSnapshot(config: Record<string, unknown>): Promis
sourcePath: available.source,
targetPath: path.join(skillsHome, available.name),
detail,
+ required: Boolean(available.required),
+ requiredReason: available.requiredReason ?? null,
});
}
@@ -147,8 +141,11 @@ export async function syncCursorSkills(
ctx: AdapterSkillContext,
desiredSkills: string[],
): Promise<AdapterSkillSnapshot> {
- const availableEntries = await listPaperclipSkillEntries(__moduleDir);
- const desiredSet = new Set(desiredSkills);
+ const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
+ const desiredSet = new Set([
+ ...desiredSkills,
+ ...availableEntries.filter((entry) => entry.required).map((entry) => entry.name),
+ ]);
const skillsHome = resolveCursorSkillsHome(ctx.config);
await fs.mkdir(skillsHome, { recursive: true });
const installed = await readInstalledSkillTargets(skillsHome);
@@ -173,7 +170,7 @@ export async function syncCursorSkills(
export function resolveCursorDesiredSkillNames(
config: Record<string, unknown>,
- availableSkillNames: string[],
+ availableEntries: Array<{ name: string; required?: boolean }>,
) {
- return resolveDesiredSkillNames(config, availableSkillNames);
+ return resolvePaperclipDesiredSkillNames(config, availableEntries);
}
diff --git a/packages/adapters/gemini-local/src/server/execute.ts b/packages/adapters/gemini-local/src/server/execute.ts
index 4816d96cbd..c33978784f 100644
--- a/packages/adapters/gemini-local/src/server/execute.ts
+++ b/packages/adapters/gemini-local/src/server/execute.ts
@@ -15,8 +15,8 @@ import {
ensurePaperclipSkillSymlink,
joinPromptSections,
ensurePathInEnv,
- listPaperclipSkillEntries,
- readPaperclipSkillSyncPreference,
+ readPaperclipRuntimeSkillEntries,
+ resolvePaperclipDesiredSkillNames,
removeMaintainerOnlySkillSymlinks,
parseObject,
redactEnvForLogs,
@@ -85,12 +85,12 @@ function geminiSkillsHome(): string {
*/
async function ensureGeminiSkillsInjected(
onLog: AdapterExecutionContext["onLog"],
+ skillsEntries: Array<{ name: string; source: string }>,
desiredSkillNames?: string[],
): Promise<void> {
- const allSkillsEntries = await listPaperclipSkillEntries(__moduleDir);
- const desiredSet = new Set(desiredSkillNames ?? allSkillsEntries.map((entry) => entry.name));
- const skillsEntries = allSkillsEntries.filter((entry) => desiredSet.has(entry.name));
- if (skillsEntries.length === 0) return;
+ const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.name));
+ const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.name));
+ if (selectedEntries.length === 0) return;
const skillsHome = geminiSkillsHome();
try {
@@ -104,7 +104,7 @@ async function ensureGeminiSkillsInjected(
}
const removedSkills = await removeMaintainerOnlySkillSymlinks(
skillsHome,
- skillsEntries.map((entry) => entry.name),
+ selectedEntries.map((entry) => entry.name),
);
for (const skillName of removedSkills) {
await onLog(
@@ -113,7 +113,7 @@ async function ensureGeminiSkillsInjected(
);
}
- for (const entry of skillsEntries) {
+ for (const entry of selectedEntries) {
const target = path.join(skillsHome, entry.name);
try {
@@ -160,12 +160,9 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
- const geminiSkillEntries = await listPaperclipSkillEntries(__moduleDir);
- const geminiPreference = readPaperclipSkillSyncPreference(config);
- const desiredGeminiSkillNames = geminiPreference.explicit
- ? geminiPreference.desiredSkills
- : geminiSkillEntries.map((entry) => entry.name);
- await ensureGeminiSkillsInjected(onLog, desiredGeminiSkillNames);
+ const geminiSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+ const desiredGeminiSkillNames = resolvePaperclipDesiredSkillNames(config, geminiSkillEntries);
+ await ensureGeminiSkillsInjected(onLog, geminiSkillEntries, desiredGeminiSkillNames);
const envConfig = parseObject(config.env);
const hasExplicitApiKey =
diff --git a/packages/adapters/gemini-local/src/server/skills.ts b/packages/adapters/gemini-local/src/server/skills.ts
index 20a202e2c8..a2776d835c 100644
--- a/packages/adapters/gemini-local/src/server/skills.ts
+++ b/packages/adapters/gemini-local/src/server/skills.ts
@@ -9,8 +9,8 @@ import type {
} from "@paperclipai/adapter-utils";
import {
ensurePaperclipSkillSymlink,
- listPaperclipSkillEntries,
- readPaperclipSkillSyncPreference,
+ readPaperclipRuntimeSkillEntries,
+ resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
@@ -29,11 +29,6 @@ function resolveGeminiSkillsHome(config: Record<string, unknown>) {
return path.join(home, ".gemini", "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" }>();
@@ -57,12 +52,9 @@ async function readInstalledSkillTargets(skillsHome: string) {
}
async function buildGeminiSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
- const availableEntries = await listPaperclipSkillEntries(__moduleDir);
+ const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
- const desiredSkills = resolveDesiredSkillNames(
- config,
- availableEntries.map((entry) => entry.name),
- );
+ const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveGeminiSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
@@ -97,6 +89,8 @@ async function buildGeminiSkillSnapshot(config: Record<string, unknown>): Promis
sourcePath: available.source,
targetPath: path.join(skillsHome, available.name),
detail,
+ required: Boolean(available.required),
+ requiredReason: available.requiredReason ?? null,
});
}
@@ -147,8 +141,11 @@ export async function syncGeminiSkills(
ctx: AdapterSkillContext,
desiredSkills: string[],
): Promise<AdapterSkillSnapshot> {
- const availableEntries = await listPaperclipSkillEntries(__moduleDir);
- const desiredSet = new Set(desiredSkills);
+ const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
+ const desiredSet = new Set([
+ ...desiredSkills,
+ ...availableEntries.filter((entry) => entry.required).map((entry) => entry.name),
+ ]);
const skillsHome = resolveGeminiSkillsHome(ctx.config);
await fs.mkdir(skillsHome, { recursive: true });
const installed = await readInstalledSkillTargets(skillsHome);
@@ -173,7 +170,7 @@ export async function syncGeminiSkills(
export function resolveGeminiDesiredSkillNames(
config: Record<string, unknown>,
- availableSkillNames: string[],
+ availableEntries: Array<{ name: string; required?: boolean }>,
) {
- return resolveDesiredSkillNames(config, availableSkillNames);
+ return resolvePaperclipDesiredSkillNames(config, availableEntries);
}
diff --git a/packages/adapters/opencode-local/src/server/execute.ts b/packages/adapters/opencode-local/src/server/execute.ts
index d514a98206..90e3c45af3 100644
--- a/packages/adapters/opencode-local/src/server/execute.ts
+++ b/packages/adapters/opencode-local/src/server/execute.ts
@@ -13,19 +13,18 @@ import {
redactEnvForLogs,
ensureAbsoluteDirectory,
ensureCommandResolvable,
+ ensurePaperclipSkillSymlink,
ensurePathInEnv,
renderTemplate,
runChildProcess,
- readPaperclipSkillSyncPreference,
+ readPaperclipRuntimeSkillEntries,
+ resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
import { isOpenCodeUnknownSessionError, parseOpenCodeJsonl } from "./parse.js";
import { ensureOpenCodeModelConfiguredAndAvailable } from "./models.js";
+import { removeMaintainerOnlySkillSymlinks } from "@paperclipai/adapter-utils/server-utils";
const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
-const PAPERCLIP_SKILLS_CANDIDATES = [
- path.resolve(__moduleDir, "../../skills"),
- path.resolve(__moduleDir, "../../../../../skills"),
-];
function firstNonEmptyLine(text: string): string {
return (
@@ -47,38 +46,34 @@ function claudeSkillsHome(): string {
return path.join(os.homedir(), ".claude", "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;
-}
-
async function ensureOpenCodeSkillsInjected(
onLog: AdapterExecutionContext["onLog"],
+ skillsEntries: Array<{ name: string; source: string }>,
desiredSkillNames?: string[],
) {
- const skillsDir = await resolvePaperclipSkillsDir();
- if (!skillsDir) return;
-
const skillsHome = claudeSkillsHome();
await fs.mkdir(skillsHome, { recursive: true });
- const entries = await fs.readdir(skillsDir, { withFileTypes: true });
- const desiredSet = new Set(desiredSkillNames ?? entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name));
- for (const entry of entries) {
- if (!entry.isDirectory()) continue;
- if (!desiredSet.has(entry.name)) continue;
- const source = path.join(skillsDir, entry.name);
+ const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.name));
+ const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.name));
+ const removedSkills = await removeMaintainerOnlySkillSymlinks(
+ skillsHome,
+ selectedEntries.map((entry) => entry.name),
+ );
+ for (const skillName of removedSkills) {
+ await onLog(
+ "stderr",
+ `[paperclip] Removed maintainer-only OpenCode skill "${skillName}" from ${skillsHome}\n`,
+ );
+ }
+ for (const entry of selectedEntries) {
const target = path.join(skillsHome, entry.name);
- const existing = await fs.lstat(target).catch(() => null);
- if (existing) continue;
try {
- await fs.symlink(source, target);
+ const result = await ensurePaperclipSkillSymlink(entry.source, target);
+ if (result === "skipped") continue;
await onLog(
"stderr",
- `[paperclip] Injected OpenCode skill "${entry.name}" into ${skillsHome}\n`,
+ `[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} OpenCode skill "${entry.name}" into ${skillsHome}\n`,
);
} catch (err) {
await onLog(
@@ -117,10 +112,12 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
- const openCodePreference = readPaperclipSkillSyncPreference(config);
+ const openCodeSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+ const desiredOpenCodeSkillNames = resolvePaperclipDesiredSkillNames(config, openCodeSkillEntries);
await ensureOpenCodeSkillsInjected(
onLog,
- openCodePreference.explicit ? openCodePreference.desiredSkills : undefined,
+ openCodeSkillEntries,
+ desiredOpenCodeSkillNames,
);
const envConfig = parseObject(config.env);
diff --git a/packages/adapters/opencode-local/src/server/skills.ts b/packages/adapters/opencode-local/src/server/skills.ts
index 32a140e957..35fe1fddd8 100644
--- a/packages/adapters/opencode-local/src/server/skills.ts
+++ b/packages/adapters/opencode-local/src/server/skills.ts
@@ -9,8 +9,8 @@ import type {
} from "@paperclipai/adapter-utils";
import {
ensurePaperclipSkillSymlink,
- listPaperclipSkillEntries,
- readPaperclipSkillSyncPreference,
+ readPaperclipRuntimeSkillEntries,
+ resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
@@ -29,11 +29,6 @@ function resolveOpenCodeSkillsHome(config: Record<string, unknown>) {
return path.join(home, ".claude", "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" }>();
@@ -57,12 +52,9 @@ async function readInstalledSkillTargets(skillsHome: string) {
}
async function buildOpenCodeSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
- const availableEntries = await listPaperclipSkillEntries(__moduleDir);
+ const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
- const desiredSkills = resolveDesiredSkillNames(
- config,
- availableEntries.map((entry) => entry.name),
- );
+ const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveOpenCodeSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
@@ -100,6 +92,8 @@ async function buildOpenCodeSkillSnapshot(config: Record<string, unknown>): Prom
sourcePath: available.source,
targetPath: path.join(skillsHome, available.name),
detail,
+ required: Boolean(available.required),
+ requiredReason: available.requiredReason ?? null,
});
}
@@ -150,8 +144,11 @@ export async function syncOpenCodeSkills(
ctx: AdapterSkillContext,
desiredSkills: string[],
): Promise<AdapterSkillSnapshot> {
- const availableEntries = await listPaperclipSkillEntries(__moduleDir);
- const desiredSet = new Set(desiredSkills);
+ const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
+ const desiredSet = new Set([
+ ...desiredSkills,
+ ...availableEntries.filter((entry) => entry.required).map((entry) => entry.name),
+ ]);
const skillsHome = resolveOpenCodeSkillsHome(ctx.config);
await fs.mkdir(skillsHome, { recursive: true });
const installed = await readInstalledSkillTargets(skillsHome);
@@ -176,7 +173,7 @@ export async function syncOpenCodeSkills(
export function resolveOpenCodeDesiredSkillNames(
config: Record<string, unknown>,
- availableSkillNames: string[],
+ availableEntries: Array<{ name: string; required?: boolean }>,
) {
- return resolveDesiredSkillNames(config, availableSkillNames);
+ return resolvePaperclipDesiredSkillNames(config, availableEntries);
}
diff --git a/packages/adapters/pi-local/src/server/execute.ts b/packages/adapters/pi-local/src/server/execute.ts
index 552d35d638..efc81222a9 100644
--- a/packages/adapters/pi-local/src/server/execute.ts
+++ b/packages/adapters/pi-local/src/server/execute.ts
@@ -15,8 +15,8 @@ import {
ensureCommandResolvable,
ensurePaperclipSkillSymlink,
ensurePathInEnv,
- listPaperclipSkillEntries,
- readPaperclipSkillSyncPreference,
+ readPaperclipRuntimeSkillEntries,
+ resolvePaperclipDesiredSkillNames,
removeMaintainerOnlySkillSymlinks,
renderTemplate,
runChildProcess,
@@ -53,18 +53,18 @@ function parseModelId(model: string | null): string | null {
async function ensurePiSkillsInjected(
onLog: AdapterExecutionContext["onLog"],
+ skillsEntries: Array<{ name: string; source: string }>,
desiredSkillNames?: string[],
) {
- const allSkillsEntries = await listPaperclipSkillEntries(__moduleDir);
- const desiredSet = new Set(desiredSkillNames ?? allSkillsEntries.map((entry) => entry.name));
- const skillsEntries = allSkillsEntries.filter((entry) => desiredSet.has(entry.name));
- if (skillsEntries.length === 0) return;
+ const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.name));
+ const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.name));
+ if (selectedEntries.length === 0) return;
const piSkillsHome = path.join(os.homedir(), ".pi", "agent", "skills");
await fs.mkdir(piSkillsHome, { recursive: true });
const removedSkills = await removeMaintainerOnlySkillSymlinks(
piSkillsHome,
- skillsEntries.map((entry) => entry.name),
+ selectedEntries.map((entry) => entry.name),
);
for (const skillName of removedSkills) {
await onLog(
@@ -73,7 +73,7 @@ async function ensurePiSkillsInjected(
);
}
- for (const entry of skillsEntries) {
+ for (const entry of selectedEntries) {
const target = path.join(piSkillsHome, entry.name);
try {
@@ -139,12 +139,9 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
await ensureSessionsDir();
// Inject skills
- const piSkillEntries = await listPaperclipSkillEntries(__moduleDir);
- const piPreference = readPaperclipSkillSyncPreference(config);
- const desiredPiSkillNames = piPreference.explicit
- ? piPreference.desiredSkills
- : piSkillEntries.map((entry) => entry.name);
- await ensurePiSkillsInjected(onLog, desiredPiSkillNames);
+ const piSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+ const desiredPiSkillNames = resolvePaperclipDesiredSkillNames(config, piSkillEntries);
+ await ensurePiSkillsInjected(onLog, piSkillEntries, desiredPiSkillNames);
// Build environment
const envConfig = parseObject(config.env);
diff --git a/packages/adapters/pi-local/src/server/skills.ts b/packages/adapters/pi-local/src/server/skills.ts
index eff2753f36..b0cb0fe387 100644
--- a/packages/adapters/pi-local/src/server/skills.ts
+++ b/packages/adapters/pi-local/src/server/skills.ts
@@ -9,8 +9,8 @@ import type {
} from "@paperclipai/adapter-utils";
import {
ensurePaperclipSkillSymlink,
- listPaperclipSkillEntries,
- readPaperclipSkillSyncPreference,
+ readPaperclipRuntimeSkillEntries,
+ resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
@@ -29,11 +29,6 @@ function resolvePiSkillsHome(config: Record<string, unknown>) {
return path.join(home, ".pi", "agent", "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" }>();
@@ -57,12 +52,9 @@ async function readInstalledSkillTargets(skillsHome: string) {
}
async function buildPiSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
- const availableEntries = await listPaperclipSkillEntries(__moduleDir);
+ const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
- const desiredSkills = resolveDesiredSkillNames(
- config,
- availableEntries.map((entry) => entry.name),
- );
+ const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolvePiSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
@@ -97,6 +89,8 @@ async function buildPiSkillSnapshot(config: Record<string, unknown>): Promise<Ad
sourcePath: available.source,
targetPath: path.join(skillsHome, available.name),
detail,
+ required: Boolean(available.required),
+ requiredReason: available.requiredReason ?? null,
});
}
@@ -147,8 +141,11 @@ export async function syncPiSkills(
ctx: AdapterSkillContext,
desiredSkills: string[],
): Promise<AdapterSkillSnapshot> {
- const availableEntries = await listPaperclipSkillEntries(__moduleDir);
- const desiredSet = new Set(desiredSkills);
+ const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
+ const desiredSet = new Set([
+ ...desiredSkills,
+ ...availableEntries.filter((entry) => entry.required).map((entry) => entry.name),
+ ]);
const skillsHome = resolvePiSkillsHome(ctx.config);
await fs.mkdir(skillsHome, { recursive: true });
const installed = await readInstalledSkillTargets(skillsHome);
@@ -173,7 +170,7 @@ export async function syncPiSkills(
export function resolvePiDesiredSkillNames(
config: Record<string, unknown>,
- availableSkillNames: string[],
+ availableEntries: Array<{ name: string; required?: boolean }>,
) {
- return resolveDesiredSkillNames(config, availableSkillNames);
+ return resolvePaperclipDesiredSkillNames(config, availableEntries);
}
diff --git a/packages/shared/src/types/adapter-skills.ts b/packages/shared/src/types/adapter-skills.ts
index 750ebaa4eb..c79483b570 100644
--- a/packages/shared/src/types/adapter-skills.ts
+++ b/packages/shared/src/types/adapter-skills.ts
@@ -12,6 +12,8 @@ export interface AgentSkillEntry {
name: string;
desired: boolean;
managed: boolean;
+ required?: boolean;
+ requiredReason?: string | null;
state: AgentSkillState;
sourcePath?: string | null;
targetPath?: string | null;
diff --git a/packages/shared/src/validators/adapter-skills.ts b/packages/shared/src/validators/adapter-skills.ts
index 07a71de505..212043ab8e 100644
--- a/packages/shared/src/validators/adapter-skills.ts
+++ b/packages/shared/src/validators/adapter-skills.ts
@@ -19,6 +19,8 @@ export const agentSkillEntrySchema = z.object({
name: z.string().min(1),
desired: z.boolean(),
managed: z.boolean(),
+ required: z.boolean().optional(),
+ requiredReason: z.string().nullable().optional(),
state: agentSkillStateSchema,
sourcePath: z.string().nullable().optional(),
targetPath: z.string().nullable().optional(),
diff --git a/server/src/__tests__/claude-local-skill-sync.test.ts b/server/src/__tests__/claude-local-skill-sync.test.ts
index 5a6f13e2bc..4bc58f7db0 100644
--- a/server/src/__tests__/claude-local-skill-sync.test.ts
+++ b/server/src/__tests__/claude-local-skill-sync.test.ts
@@ -16,6 +16,7 @@ describe("claude local skill sync", () => {
expect(snapshot.mode).toBe("ephemeral");
expect(snapshot.supported).toBe(true);
expect(snapshot.desiredSkills).toContain("paperclip");
+ expect(snapshot.entries.find((entry) => entry.name === "paperclip")?.required).toBe(true);
expect(snapshot.entries.find((entry) => entry.name === "paperclip")?.state).toBe("configured");
});
@@ -31,8 +32,8 @@ describe("claude local skill sync", () => {
},
}, ["paperclip"]);
- expect(snapshot.desiredSkills).toEqual(["paperclip"]);
+ expect(snapshot.desiredSkills).toContain("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");
+ expect(snapshot.entries.find((entry) => entry.name === "paperclip-create-agent")?.state).toBe("configured");
});
});
diff --git a/server/src/__tests__/codex-local-skill-sync.test.ts b/server/src/__tests__/codex-local-skill-sync.test.ts
index 79c1d89581..13be991e5d 100644
--- a/server/src/__tests__/codex-local-skill-sync.test.ts
+++ b/server/src/__tests__/codex-local-skill-sync.test.ts
@@ -39,7 +39,8 @@ describe("codex local skill sync", () => {
const before = await listCodexSkills(ctx);
expect(before.mode).toBe("persistent");
- expect(before.desiredSkills).toEqual(["paperclip"]);
+ expect(before.desiredSkills).toContain("paperclip");
+ expect(before.entries.find((entry) => entry.name === "paperclip")?.required).toBe(true);
expect(before.entries.find((entry) => entry.name === "paperclip")?.state).toBe("missing");
const after = await syncCodexSkills(ctx, ["paperclip"]);
@@ -47,7 +48,7 @@ describe("codex local skill sync", () => {
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 () => {
+ it("keeps required bundled Paperclip skills installed even when the desired set is emptied", async () => {
const codexHome = await makeTempDir("paperclip-codex-skill-prune-");
cleanupDirs.add(codexHome);
@@ -80,8 +81,8 @@ describe("codex local skill sync", () => {
} 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();
+ expect(after.desiredSkills).toContain("paperclip");
+ expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");
+ expect((await fs.lstat(path.join(codexHome, "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
});
diff --git a/server/src/__tests__/cursor-local-execute.test.ts b/server/src/__tests__/cursor-local-execute.test.ts
index 937315d0c7..97839897be 100644
--- a/server/src/__tests__/cursor-local-execute.test.ts
+++ b/server/src/__tests__/cursor-local-execute.test.ts
@@ -46,6 +46,13 @@ type CapturePayload = {
paperclipEnvKeys: string[];
};
+async function createSkillDir(root: string, name: string) {
+ const skillDir = path.join(root, name);
+ await fs.mkdir(skillDir, { recursive: true });
+ await fs.writeFile(path.join(skillDir, "SKILL.md"), `---\nname: ${name}\n---\n`, "utf8");
+ return skillDir;
+}
+
describe("cursor execute", () => {
it("injects paperclip env vars and prompt note by default", async () => {
const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-cursor-execute-"));
@@ -179,4 +186,77 @@ describe("cursor execute", () => {
await fs.rm(root, { recursive: true, force: true });
}
});
+
+ it("injects company-library runtime skills into the Cursor skills home before execution", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-cursor-execute-runtime-skill-"));
+ const workspace = path.join(root, "workspace");
+ const commandPath = path.join(root, "agent");
+ const runtimeSkillsRoot = path.join(root, "runtime-skills");
+ await fs.mkdir(workspace, { recursive: true });
+ await writeFakeCursorCommand(commandPath);
+
+ const paperclipDir = await createSkillDir(runtimeSkillsRoot, "paperclip");
+ const asciiHeartDir = await createSkillDir(runtimeSkillsRoot, "ascii-heart");
+
+ const previousHome = process.env.HOME;
+ process.env.HOME = root;
+
+ try {
+ const result = await execute({
+ runId: "run-3",
+ agent: {
+ id: "agent-1",
+ companyId: "company-1",
+ name: "Cursor Coder",
+ adapterType: "cursor",
+ adapterConfig: {},
+ },
+ runtime: {
+ sessionId: null,
+ sessionParams: null,
+ sessionDisplayId: null,
+ taskKey: null,
+ },
+ config: {
+ command: commandPath,
+ cwd: workspace,
+ model: "auto",
+ paperclipRuntimeSkills: [
+ {
+ name: "paperclip",
+ source: paperclipDir,
+ required: true,
+ requiredReason: "Bundled Paperclip skills are always available for local adapters.",
+ },
+ {
+ name: "ascii-heart",
+ source: asciiHeartDir,
+ },
+ ],
+ paperclipSkillSync: {
+ desiredSkills: ["ascii-heart"],
+ },
+ promptTemplate: "Follow the paperclip heartbeat.",
+ },
+ context: {},
+ authToken: "run-jwt-token",
+ onLog: async () => {},
+ onMeta: async () => {},
+ });
+
+ expect(result.exitCode).toBe(0);
+ expect(result.errorMessage).toBeNull();
+ expect((await fs.lstat(path.join(root, ".cursor", "skills", "ascii-heart"))).isSymbolicLink()).toBe(true);
+ expect(await fs.realpath(path.join(root, ".cursor", "skills", "ascii-heart"))).toBe(
+ await fs.realpath(asciiHeartDir),
+ );
+ } finally {
+ if (previousHome === undefined) {
+ delete process.env.HOME;
+ } else {
+ process.env.HOME = previousHome;
+ }
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
});
diff --git a/server/src/__tests__/cursor-local-skill-sync.test.ts b/server/src/__tests__/cursor-local-skill-sync.test.ts
index 18483d32f0..d26c99e408 100644
--- a/server/src/__tests__/cursor-local-skill-sync.test.ts
+++ b/server/src/__tests__/cursor-local-skill-sync.test.ts
@@ -11,6 +11,13 @@ async function makeTempDir(prefix: string): Promise<string> {
return fs.mkdtemp(path.join(os.tmpdir(), prefix));
}
+async function createSkillDir(root: string, name: string) {
+ const skillDir = path.join(root, name);
+ await fs.mkdir(skillDir, { recursive: true });
+ await fs.writeFile(path.join(skillDir, "SKILL.md"), `---\nname: ${name}\n---\n`, "utf8");
+ return skillDir;
+}
+
describe("cursor local skill sync", () => {
const cleanupDirs = new Set<string>();
@@ -39,7 +46,8 @@ describe("cursor local skill sync", () => {
const before = await listCursorSkills(ctx);
expect(before.mode).toBe("persistent");
- expect(before.desiredSkills).toEqual(["paperclip"]);
+ expect(before.desiredSkills).toContain("paperclip");
+ expect(before.entries.find((entry) => entry.name === "paperclip")?.required).toBe(true);
expect(before.entries.find((entry) => entry.name === "paperclip")?.state).toBe("missing");
const after = await syncCursorSkills(ctx, ["paperclip"]);
@@ -47,7 +55,53 @@ describe("cursor local skill sync", () => {
expect((await fs.lstat(path.join(home, ".cursor", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
- it("removes stale managed Paperclip skills when the desired set is emptied", async () => {
+ it("recognizes company-library runtime skills supplied outside the bundled Paperclip directory", async () => {
+ const home = await makeTempDir("paperclip-cursor-runtime-skills-home-");
+ const runtimeSkills = await makeTempDir("paperclip-cursor-runtime-skills-src-");
+ cleanupDirs.add(home);
+ cleanupDirs.add(runtimeSkills);
+
+ const paperclipDir = await createSkillDir(runtimeSkills, "paperclip");
+ const asciiHeartDir = await createSkillDir(runtimeSkills, "ascii-heart");
+
+ const ctx = {
+ agentId: "agent-3",
+ companyId: "company-1",
+ adapterType: "cursor",
+ config: {
+ env: {
+ HOME: home,
+ },
+ paperclipRuntimeSkills: [
+ {
+ name: "paperclip",
+ source: paperclipDir,
+ required: true,
+ requiredReason: "Bundled Paperclip skills are always available for local adapters.",
+ },
+ {
+ name: "ascii-heart",
+ source: asciiHeartDir,
+ },
+ ],
+ paperclipSkillSync: {
+ desiredSkills: ["ascii-heart"],
+ },
+ },
+ } as const;
+
+ const before = await listCursorSkills(ctx);
+ expect(before.warnings).toEqual([]);
+ expect(before.desiredSkills).toEqual(["paperclip", "ascii-heart"]);
+ expect(before.entries.find((entry) => entry.name === "ascii-heart")?.state).toBe("missing");
+
+ const after = await syncCursorSkills(ctx, ["ascii-heart"]);
+ expect(after.warnings).toEqual([]);
+ expect(after.entries.find((entry) => entry.name === "ascii-heart")?.state).toBe("installed");
+ expect((await fs.lstat(path.join(home, ".cursor", "skills", "ascii-heart"))).isSymbolicLink()).toBe(true);
+ });
+
+ it("keeps required bundled Paperclip skills installed even when the desired set is emptied", async () => {
const home = await makeTempDir("paperclip-cursor-skill-prune-");
cleanupDirs.add(home);
@@ -80,8 +134,8 @@ describe("cursor local skill sync", () => {
} as const;
const after = await syncCursorSkills(clearedCtx, []);
- expect(after.desiredSkills).toEqual([]);
- expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("available");
- await expect(fs.lstat(path.join(home, ".cursor", "skills", "paperclip"))).rejects.toThrow();
+ expect(after.desiredSkills).toContain("paperclip");
+ expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");
+ expect((await fs.lstat(path.join(home, ".cursor", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
});
diff --git a/server/src/__tests__/gemini-local-skill-sync.test.ts b/server/src/__tests__/gemini-local-skill-sync.test.ts
index 75f933b573..8619973bfa 100644
--- a/server/src/__tests__/gemini-local-skill-sync.test.ts
+++ b/server/src/__tests__/gemini-local-skill-sync.test.ts
@@ -39,7 +39,8 @@ describe("gemini local skill sync", () => {
const before = await listGeminiSkills(ctx);
expect(before.mode).toBe("persistent");
- expect(before.desiredSkills).toEqual(["paperclip"]);
+ expect(before.desiredSkills).toContain("paperclip");
+ expect(before.entries.find((entry) => entry.name === "paperclip")?.required).toBe(true);
expect(before.entries.find((entry) => entry.name === "paperclip")?.state).toBe("missing");
const after = await syncGeminiSkills(ctx, ["paperclip"]);
@@ -47,7 +48,7 @@ describe("gemini local skill sync", () => {
expect((await fs.lstat(path.join(home, ".gemini", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
- it("removes stale managed Paperclip skills when the desired set is emptied", async () => {
+ it("keeps required bundled Paperclip skills installed even when the desired set is emptied", async () => {
const home = await makeTempDir("paperclip-gemini-skill-prune-");
cleanupDirs.add(home);
@@ -80,8 +81,8 @@ describe("gemini local skill sync", () => {
} as const;
const after = await syncGeminiSkills(clearedCtx, []);
- expect(after.desiredSkills).toEqual([]);
- expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("available");
- await expect(fs.lstat(path.join(home, ".gemini", "skills", "paperclip"))).rejects.toThrow();
+ expect(after.desiredSkills).toContain("paperclip");
+ expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");
+ expect((await fs.lstat(path.join(home, ".gemini", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
});
diff --git a/server/src/__tests__/opencode-local-skill-sync.test.ts b/server/src/__tests__/opencode-local-skill-sync.test.ts
index 38f2f941d5..bf1130646a 100644
--- a/server/src/__tests__/opencode-local-skill-sync.test.ts
+++ b/server/src/__tests__/opencode-local-skill-sync.test.ts
@@ -40,7 +40,8 @@ describe("opencode local skill sync", () => {
const before = await listOpenCodeSkills(ctx);
expect(before.mode).toBe("persistent");
expect(before.warnings).toContain("OpenCode currently uses the shared Claude skills home (~/.claude/skills).");
- expect(before.desiredSkills).toEqual(["paperclip"]);
+ expect(before.desiredSkills).toContain("paperclip");
+ expect(before.entries.find((entry) => entry.name === "paperclip")?.required).toBe(true);
expect(before.entries.find((entry) => entry.name === "paperclip")?.state).toBe("missing");
const after = await syncOpenCodeSkills(ctx, ["paperclip"]);
@@ -48,7 +49,7 @@ describe("opencode local skill sync", () => {
expect((await fs.lstat(path.join(home, ".claude", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
- it("removes stale managed Paperclip skills when the desired set is emptied", async () => {
+ it("keeps required bundled Paperclip skills installed even when the desired set is emptied", async () => {
const home = await makeTempDir("paperclip-opencode-skill-prune-");
cleanupDirs.add(home);
@@ -81,8 +82,8 @@ describe("opencode local skill sync", () => {
} as const;
const after = await syncOpenCodeSkills(clearedCtx, []);
- expect(after.desiredSkills).toEqual([]);
- expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("available");
- await expect(fs.lstat(path.join(home, ".claude", "skills", "paperclip"))).rejects.toThrow();
+ expect(after.desiredSkills).toContain("paperclip");
+ expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");
+ expect((await fs.lstat(path.join(home, ".claude", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
});
diff --git a/server/src/__tests__/pi-local-skill-sync.test.ts b/server/src/__tests__/pi-local-skill-sync.test.ts
index d2a00edaf3..77790c017f 100644
--- a/server/src/__tests__/pi-local-skill-sync.test.ts
+++ b/server/src/__tests__/pi-local-skill-sync.test.ts
@@ -39,7 +39,8 @@ describe("pi local skill sync", () => {
const before = await listPiSkills(ctx);
expect(before.mode).toBe("persistent");
- expect(before.desiredSkills).toEqual(["paperclip"]);
+ expect(before.desiredSkills).toContain("paperclip");
+ expect(before.entries.find((entry) => entry.name === "paperclip")?.required).toBe(true);
expect(before.entries.find((entry) => entry.name === "paperclip")?.state).toBe("missing");
const after = await syncPiSkills(ctx, ["paperclip"]);
@@ -47,7 +48,7 @@ describe("pi local skill sync", () => {
expect((await fs.lstat(path.join(home, ".pi", "agent", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
- it("removes stale managed Paperclip skills when the desired set is emptied", async () => {
+ it("keeps required bundled Paperclip skills installed even when the desired set is emptied", async () => {
const home = await makeTempDir("paperclip-pi-skill-prune-");
cleanupDirs.add(home);
@@ -80,8 +81,8 @@ describe("pi local skill sync", () => {
} as const;
const after = await syncPiSkills(clearedCtx, []);
- expect(after.desiredSkills).toEqual([]);
- expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("available");
- await expect(fs.lstat(path.join(home, ".pi", "agent", "skills", "paperclip"))).rejects.toThrow();
+ expect(after.desiredSkills).toContain("paperclip");
+ expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");
+ expect((await fs.lstat(path.join(home, ".pi", "agent", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
});
diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.ts
index 9e429df644..a64ca04280 100644
--- a/server/src/routes/agents.ts
+++ b/server/src/routes/agents.ts
@@ -29,6 +29,7 @@ import {
agentService,
accessService,
approvalService,
+ companySkillService,
heartbeatService,
issueApprovalService,
issueService,
@@ -66,6 +67,7 @@ export function agentRoutes(db: Db) {
const heartbeat = heartbeatService(db);
const issueApprovalsSvc = issueApprovalService(db);
const secretsSvc = secretService(db);
+ const companySkills = companySkillService(db);
const strictSecretsMode = process.env.PAPERCLIP_SECRETS_STRICT_MODE === "true";
function canCreateAgents(agent: { role: string; permissions: Record<string, unknown> | null | undefined }) {
@@ -354,6 +356,14 @@ export function agentRoutes(db: Db) {
};
}
+ async function buildRuntimeSkillConfig(companyId: string, config: Record<string, unknown>) {
+ const runtimeSkillEntries = await companySkills.listRuntimeSkillEntries(companyId);
+ return {
+ ...config,
+ paperclipRuntimeSkills: runtimeSkillEntries,
+ };
+ }
+
function redactForRestrictedAgentView(agent: Awaited<ReturnType<typeof svc.getById>>) {
if (!agent) return null;
return {
@@ -493,7 +503,9 @@ export function agentRoutes(db: Db) {
const preference = readPaperclipSkillSyncPreference(
agent.adapterConfig as Record<string, unknown>,
);
- res.json(buildUnsupportedSkillSnapshot(agent.adapterType, preference.desiredSkills));
+ const runtimeSkillEntries = await companySkills.listRuntimeSkillEntries(agent.companyId);
+ const requiredSkills = runtimeSkillEntries.filter((entry) => entry.required).map((entry) => entry.name);
+ res.json(buildUnsupportedSkillSnapshot(agent.adapterType, Array.from(new Set([...requiredSkills, ...preference.desiredSkills]))));
return;
}
@@ -501,11 +513,12 @@ export function agentRoutes(db: Db) {
agent.companyId,
agent.adapterConfig,
);
+ const runtimeSkillConfig = await buildRuntimeSkillConfig(agent.companyId, runtimeConfig);
const snapshot = await adapter.listSkills({
agentId: agent.id,
companyId: agent.companyId,
adapterType: agent.adapterType,
- config: runtimeConfig,
+ config: runtimeSkillConfig,
});
res.json(snapshot);
});
@@ -522,13 +535,16 @@ export function agentRoutes(db: Db) {
}
await assertCanUpdateAgent(req, agent);
- const desiredSkills = Array.from(
+ const requestedSkills = Array.from(
new Set(
(req.body.desiredSkills as string[])
.map((value) => value.trim())
.filter(Boolean),
),
);
+ const runtimeSkillEntries = await companySkills.listRuntimeSkillEntries(agent.companyId);
+ const requiredSkills = runtimeSkillEntries.filter((entry) => entry.required).map((entry) => entry.name);
+ const desiredSkills = Array.from(new Set([...requiredSkills, ...requestedSkills]));
const nextAdapterConfig = writePaperclipSkillSyncPreference(
agent.adapterConfig as Record<string, unknown>,
desiredSkills,
@@ -553,19 +569,23 @@ export function agentRoutes(db: Db) {
updated.companyId,
updated.adapterConfig,
);
+ const runtimeSkillConfig = {
+ ...runtimeConfig,
+ paperclipRuntimeSkills: runtimeSkillEntries,
+ };
const snapshot = adapter?.syncSkills
? await adapter.syncSkills({
agentId: updated.id,
companyId: updated.companyId,
adapterType: updated.adapterType,
- config: runtimeConfig,
+ config: runtimeSkillConfig,
}, desiredSkills)
: adapter?.listSkills
? await adapter.listSkills({
agentId: updated.id,
companyId: updated.companyId,
adapterType: updated.adapterType,
- config: runtimeConfig,
+ config: runtimeSkillConfig,
})
: buildUnsupportedSkillSnapshot(updated.adapterType, desiredSkills);
diff --git a/server/src/services/company-skills.ts b/server/src/services/company-skills.ts
index 90895d7a7f..1ba24db73e 100644
--- a/server/src/services/company-skills.ts
+++ b/server/src/services/company-skills.ts
@@ -4,6 +4,8 @@ import { fileURLToPath } from "node:url";
import { and, asc, eq } from "drizzle-orm";
import type { Db } from "@paperclipai/db";
import { companySkills } from "@paperclipai/db";
+import { readPaperclipSkillSyncPreference } from "@paperclipai/adapter-utils/server-utils";
+import type { PaperclipSkillEntry } from "@paperclipai/adapter-utils/server-utils";
import type {
CompanySkill,
CompanySkillCreateRequest,
@@ -20,7 +22,6 @@ import type {
CompanySkillUsageAgent,
} from "@paperclipai/shared";
import { normalizeAgentUrlKey } from "@paperclipai/shared";
-import { readPaperclipSkillSyncPreference } from "@paperclipai/adapter-utils/server-utils";
import { findServerAdapter } from "../adapters/index.js";
import { resolvePaperclipInstanceRoot } from "../home-paths.js";
import { notFound, unprocessable } from "../errors.js";
@@ -959,11 +960,15 @@ export function companySkillService(db: Db) {
agent.companyId,
agent.adapterConfig as Record<string, unknown>,
);
+ const runtimeSkillEntries = await listRuntimeSkillEntries(agent.companyId);
const snapshot = await adapter.listSkills({
agentId: agent.id,
companyId: agent.companyId,
adapterType: agent.adapterType,
- config: runtimeConfig,
+ config: {
+ ...runtimeConfig,
+ paperclipRuntimeSkills: runtimeSkillEntries,
+ },
});
actualState = snapshot.entries.find((entry) => entry.name === slug)?.state
?? (snapshot.supported ? "missing" : "unsupported");
@@ -1219,6 +1224,56 @@ export function companySkillService(db: Db) {
return skillDir;
}
+ async function materializeRuntimeSkillFiles(companyId: string, skill: CompanySkill) {
+ const runtimeRoot = path.resolve(resolveManagedSkillsRoot(companyId), "__runtime__");
+ const skillDir = path.resolve(runtimeRoot, skill.slug);
+ await fs.rm(skillDir, { recursive: true, force: true });
+ await fs.mkdir(skillDir, { recursive: true });
+
+ for (const entry of skill.fileInventory) {
+ const detail = await readFile(companyId, skill.id, entry.path).catch(() => null);
+ if (!detail) continue;
+ const targetPath = path.resolve(skillDir, entry.path);
+ await fs.mkdir(path.dirname(targetPath), { recursive: true });
+ await fs.writeFile(targetPath, detail.content, "utf8");
+ }
+
+ return skillDir;
+ }
+
+ async function listRuntimeSkillEntries(companyId: string): Promise<PaperclipSkillEntry[]> {
+ await ensureBundledSkills(companyId);
+ const rows = await db
+ .select()
+ .from(companySkills)
+ .where(eq(companySkills.companyId, companyId))
+ .orderBy(asc(companySkills.name), asc(companySkills.slug));
+
+ const out: PaperclipSkillEntry[] = [];
+ for (const row of rows) {
+ const skill = toCompanySkill(row);
+ const sourceKind = asString(getSkillMeta(skill).sourceKind);
+ let source = normalizeSkillDirectory(skill);
+ if (!source) {
+ source = await materializeRuntimeSkillFiles(companyId, skill).catch(() => null);
+ }
+ if (!source) continue;
+
+ const required = sourceKind === "paperclip_bundled";
+ out.push({
+ name: skill.slug,
+ source,
+ required,
+ requiredReason: required
+ ? "Bundled Paperclip skills are always available for local adapters."
+ : null,
+ });
+ }
+
+ out.sort((left, right) => left.name.localeCompare(right.name));
+ return out;
+ }
+
async function importPackageFiles(companyId: string, files: Record<string, string>): Promise<CompanySkill[]> {
await ensureBundledSkills(companyId);
const normalizedFiles = normalizePackageFileMap(files);
@@ -1330,5 +1385,6 @@ export function companySkillService(db: Db) {
importFromSource,
importPackageFiles,
installUpdate,
+ listRuntimeSkillEntries,
};
}
diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.ts
index e924359c07..3f751e7a29 100644
--- a/server/src/services/heartbeat.ts
+++ b/server/src/services/heartbeat.ts
@@ -22,6 +22,7 @@ import type { AdapterExecutionResult, AdapterInvocationMeta, AdapterSessionCodec
import { createLocalAgentJwt } from "../agent-auth-jwt.js";
import { parseObject, asBoolean, asNumber, appendWithCap, MAX_EXCERPT_BYTES } from "../adapters/utils.js";
import { costService } from "./costs.js";
+import { companySkillService } from "./company-skills.js";
import { secretService } from "./secrets.js";
import { resolveDefaultAgentWorkspaceDir } from "../home-paths.js";
import { summarizeHeartbeatRunResultJson } from "./heartbeat-run-summary.js";
@@ -555,6 +556,7 @@ function resolveNextSessionState(input: {
export function heartbeatService(db: Db) {
const runLogStore = getRunLogStore();
const secretsSvc = secretService(db);
+ const companySkills = companySkillService(db);
const issuesSvc = issueService(db);
const activeRunExecutions = new Set<string>();
@@ -1463,6 +1465,11 @@ export function heartbeatService(db: Db) {
agent.companyId,
mergedConfig,
);
+ const runtimeSkillEntries = await companySkills.listRuntimeSkillEntries(agent.companyId);
+ const runtimeConfig = {
+ ...resolvedConfig,
+ paperclipRuntimeSkills: runtimeSkillEntries,
+ };
const issueRef = issueId
? await db
.select({
@@ -1761,7 +1768,7 @@ export function heartbeatService(db: Db) {
runId: run.id,
agent,
runtime: runtimeForAdapter,
- config: resolvedConfig,
+ config: runtimeConfig,
context,
onLog,
onMeta: onAdapterMeta,
diff --git a/ui/src/pages/AgentDetail.tsx b/ui/src/pages/AgentDetail.tsx
index d34eaead1c..ec94ea40d5 100644
--- a/ui/src/pages/AgentDetail.tsx
+++ b/ui/src/pages/AgentDetail.tsx
@@ -30,6 +30,7 @@ import { formatCents, formatDate, relativeTime, formatTokens } from "../lib/util
import { cn } from "../lib/utils";
import { Button } from "@/components/ui/button";
import { Tabs } from "@/components/ui/tabs";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
import {
Popover,
PopoverContent,
@@ -1225,12 +1226,19 @@ function AgentSkillsTab({
return "Unknown";
}
}, [skillSnapshot?.mode]);
+ const unsupportedSkillMessage = useMemo(() => {
+ if (skillSnapshot?.mode !== "unsupported") return null;
+ if (agent.adapterType === "openclaw_gateway") {
+ return "Paperclip cannot manage OpenClaw skills here. Visit your OpenClaw instance to manage this agent's skills.";
+ }
+ return "Paperclip cannot manage skills for this adapter yet. Manage them in the adapter directly.";
+ }, [agent.adapterType, skillSnapshot?.mode]);
const hasUnsavedChanges = !arraysEqual(skillDraft, lastSavedSkills);
const saveStatusLabel = syncSkills.isPending
? "Saving changes..."
: hasUnsavedChanges
? "Saving soon..."
- : "Changes save automatically";
+ : null;
return (
<div className="max-w-4xl space-y-5">
@@ -1239,12 +1247,14 @@ function AgentSkillsTab({
to="/skills"
className="text-sm font-medium text-foreground underline-offset-4 no-underline transition-colors hover:text-foreground/70 hover:underline"
>
- View company library
+ View company skills library
</Link>
- <div className="flex items-center gap-2 text-xs text-muted-foreground">
- {syncSkills.isPending ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : null}
- <span>{saveStatusLabel}</span>
- </div>
+ {saveStatusLabel ? (
+ <div className="flex items-center gap-2 text-xs text-muted-foreground">
+ {syncSkills.isPending ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : null}
+ <span>{saveStatusLabel}</span>
+ </div>
+ ) : null}
</div>
{skillSnapshot?.warnings.length ? (
@@ -1255,6 +1265,12 @@ function AgentSkillsTab({
</div>
) : null}
+ {unsupportedSkillMessage ? (
+ <div className="rounded-xl border border-border px-4 py-3 text-sm text-muted-foreground">
+ {unsupportedSkillMessage}
+ </div>
+ ) : null}
+
{isLoading ? (
<PageSkeleton variant="list" />
) : (
@@ -1268,22 +1284,46 @@ function AgentSkillsTab({
(companySkills ?? []).map((skill) => {
const checked = skillDraft.includes(skill.slug);
const adapterEntry = adapterEntryByName.get(skill.slug);
+ const required = Boolean(adapterEntry?.required);
+ const disabled = required || skillSnapshot?.mode === "unsupported";
+ const checkbox = (
+ <input
+ type="checkbox"
+ checked={checked}
+ disabled={disabled}
+ onChange={(event) => {
+ const next = event.target.checked
+ ? Array.from(new Set([...skillDraft, skill.slug]))
+ : skillDraft.filter((value) => value !== skill.slug);
+ setSkillDraft(next);
+ }}
+ className="mt-0.5 disabled:cursor-not-allowed disabled:opacity-60"
+ />
+ );
return (
<label
key={skill.id}
className="flex items-start gap-3 border-b border-border px-3 py-3 text-sm last:border-b-0 hover:bg-accent/20"
>
- <input
- type="checkbox"
- checked={checked}
- onChange={(event) => {
- const next = event.target.checked
- ? Array.from(new Set([...skillDraft, skill.slug]))
- : skillDraft.filter((value) => value !== skill.slug);
- setSkillDraft(next);
- }}
- className="mt-0.5"
- />
+ {required && adapterEntry?.requiredReason ? (
+ <Tooltip>
+ <TooltipTrigger asChild>
+ <span>{checkbox}</span>
+ </TooltipTrigger>
+ <TooltipContent side="top">{adapterEntry.requiredReason}</TooltipContent>
+ </Tooltip>
+ ) : skillSnapshot?.mode === "unsupported" ? (
+ <Tooltip>
+ <TooltipTrigger asChild>
+ <span>{checkbox}</span>
+ </TooltipTrigger>
+ <TooltipContent side="top">
+ {unsupportedSkillMessage ?? "Manage skills in the adapter directly."}
+ </TooltipContent>
+ </Tooltip>
+ ) : (
+ checkbox
+ )}
<div className="min-w-0 flex-1">
<div className="flex items-center justify-between gap-3">
<span className="truncate font-medium">{skill.name}</span>