aevgarik/paperclip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Namespace company skill identities

Browse Source 
Persist canonical namespaced skill keys, split adapter runtime names from skill keys, and update portability/import flows to carry the canonical identity end-to-end.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta
2026-03-16 18:27:20 -05:00
parent bb46423969
commit 5890b318c4
39 changed files with 9902 additions and 309 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
packages/adapter-utils/src/server-utils.ts
View File

@@ -38,7 +38,8 @@ const PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES = [
];
export interface PaperclipSkillEntry {
name: string;
key: string;
runtimeName: string;
source: string;
required?: boolean;
requiredReason?: string | null;
@@ -306,7 +307,8 @@ export async function listPaperclipSkillEntries(
return entries
.filter((entry) => entry.isDirectory())
.map((entry) => ({
name: entry.name,
key: `paperclipai/paperclip/${entry.name}`,
runtimeName: entry.name,
source: path.join(root, entry.name),
required: true,
requiredReason: "Bundled Paperclip skills are always available for local adapters.",
@@ -321,11 +323,13 @@ function normalizeConfiguredPaperclipRuntimeSkills(value: unknown): PaperclipSki
const out: PaperclipSkillEntry[] = [];
for (const rawEntry of value) {
const entry = parseObject(rawEntry);
const name = asString(entry.name, "").trim();
const key = asString(entry.key, asString(entry.name, "")).trim();
const runtimeName = asString(entry.runtimeName, asString(entry.name, "")).trim();
const source = asString(entry.source, "").trim();
if (!name || !source) continue;
if (!key || !runtimeName || !source) continue;
out.push({
name,
key,
runtimeName,
source,
required: asBoolean(entry.required, false),
requiredReason:
@@ -349,13 +353,13 @@ export async function readPaperclipRuntimeSkillEntries(
export async function readPaperclipSkillMarkdown(
moduleDir: string,
skillName: string,
skillKey: string,
): Promise<string | null> {
const normalized = skillName.trim().toLowerCase();
const normalized = skillKey.trim().toLowerCase();
if (!normalized) return null;
const entries = await listPaperclipSkillEntries(moduleDir);
const match = entries.find((entry) => entry.name === normalized);
const match = entries.find((entry) => entry.key === normalized);
if (!match) return null;
try {
@@ -389,12 +393,12 @@ export function readPaperclipSkillSyncPreference(config: Record<string, unknown>
export function resolvePaperclipDesiredSkillNames(
config: Record<string, unknown>,
availableEntries: Array<{ name: string; required?: boolean }>,
availableEntries: Array<{ key: string; required?: boolean }>,
): string[] {
const preference = readPaperclipSkillSyncPreference(config);
const requiredSkills = availableEntries
.filter((entry) => entry.required)
.map((entry) => entry.name);
.map((entry) => entry.key);
if (!preference.explicit) {
return Array.from(new Set(requiredSkills));
}

3
packages/adapter-utils/src/types.ts
View File

@@ -158,7 +158,8 @@ export type AdapterSkillState =
| "external";
export interface AdapterSkillEntry {
name: string;
key: string;
runtimeName: string | null;
desired: boolean;
managed: boolean;
required?: boolean;

4
packages/adapters/claude-local/src/server/execute.ts
View File

@@ -49,10 +49,10 @@ async function buildSkillsDir(config: Record<string, unknown>): Promise<string>
),
);
for (const entry of availableEntries) {
if (!desiredNames.has(entry.name)) continue;
if (!desiredNames.has(entry.key)) continue;
await fs.symlink(
entry.source,
path.join(target, entry.name),
path.join(target, entry.runtimeName),
);
}
return tmp;

20
packages/adapters/claude-local/src/server/skills.ts
View File

@@ -14,17 +14,18 @@ const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
async function buildClaudeSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
name: entry.name,
desired: desiredSet.has(entry.name),
key: entry.key,
runtimeName: entry.runtimeName,
desired: desiredSet.has(entry.key),
managed: true,
state: desiredSet.has(entry.name) ? "configured" : "available",
state: desiredSet.has(entry.key) ? "configured" : "available",
sourcePath: entry.source,
targetPath: null,
detail: desiredSet.has(entry.name)
detail: desiredSet.has(entry.key)
? "Will be mounted into the ephemeral Claude skill directory on the next run."
: null,
required: Boolean(entry.required),
@@ -33,10 +34,11 @@ async function buildClaudeSkillSnapshot(config: Record<string, unknown>): Promis
const warnings: string[] = [];
for (const desiredSkill of desiredSkills) {
if (availableByName.has(desiredSkill)) continue;
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
name: desiredSkill,
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
@@ -46,7 +48,7 @@ async function buildClaudeSkillSnapshot(config: Record<string, unknown>): Promis
});
}
entries.sort((left, right) => left.name.localeCompare(right.name));
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
adapterType: "claude_local",
@@ -71,7 +73,7 @@ export async function syncClaudeSkills(
export function resolveClaudeDesiredSkillNames(
config: Record<string, unknown>,
availableEntries: Array<{ name: string; required?: boolean }>,
availableEntries: Array<{ key: string; required?: boolean }>,
) {
return resolvePaperclipDesiredSkillNames(config, availableEntries);
}

18
packages/adapters/codex-local/src/server/execute.ts
View File

@@ -99,7 +99,7 @@ async function isLikelyPaperclipRuntimeSkillSource(candidate: string, skillName:
type EnsureCodexSkillsInjectedOptions = {
skillsHome?: string;
skillsEntries?: Array<{ name: string; source: string }>;
skillsEntries?: Array<{ key: string; runtimeName: string; source: string }>;
desiredSkillNames?: string[];
linkSkill?: (source: string, target: string) => Promise<void>;
};
@@ -110,16 +110,16 @@ export async function ensureCodexSkillsInjected(
) {
const allSkillsEntries = options.skillsEntries ?? await readPaperclipRuntimeSkillEntries({}, __moduleDir);
const desiredSkillNames =
options.desiredSkillNames ?? allSkillsEntries.map((entry) => entry.name);
options.desiredSkillNames ?? allSkillsEntries.map((entry) => entry.key);
const desiredSet = new Set(desiredSkillNames);
const skillsEntries = allSkillsEntries.filter((entry) => desiredSet.has(entry.name));
const skillsEntries = allSkillsEntries.filter((entry) => desiredSet.has(entry.key));
if (skillsEntries.length === 0) return;
const skillsHome = options.skillsHome ?? path.join(resolveCodexHomeDir(process.env), "skills");
await fs.mkdir(skillsHome, { recursive: true });
const removedSkills = await removeMaintainerOnlySkillSymlinks(
skillsHome,
skillsEntries.map((entry) => entry.name),
skillsEntries.map((entry) => entry.runtimeName),
);
for (const skillName of removedSkills) {
await onLog(
@@ -129,7 +129,7 @@ export async function ensureCodexSkillsInjected(
}
const linkSkill = options.linkSkill;
for (const entry of skillsEntries) {
const target = path.join(skillsHome, entry.name);
const target = path.join(skillsHome, entry.runtimeName);
try {
const existing = await fs.lstat(target).catch(() => null);
@@ -141,7 +141,7 @@ export async function ensureCodexSkillsInjected(
if (
resolvedLinkedPath &&
resolvedLinkedPath !== entry.source &&
(await isLikelyPaperclipRuntimeSkillSource(resolvedLinkedPath, entry.name))
(await isLikelyPaperclipRuntimeSkillSource(resolvedLinkedPath, entry.runtimeName))
) {
await fs.unlink(target);
if (linkSkill) {
@@ -151,7 +151,7 @@ export async function ensureCodexSkillsInjected(
}
await onLog(
"stderr",
`[paperclip] Repaired Codex skill "${entry.name}" into ${skillsHome}\n`,
`[paperclip] Repaired Codex skill "${entry.key}" into ${skillsHome}\n`,
);
continue;
}
@@ -162,12 +162,12 @@ export async function ensureCodexSkillsInjected(
await onLog(
"stderr",
`[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} Codex skill "${entry.name}" into ${skillsHome}\n`,
`[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} Codex skill "${entry.key}" into ${skillsHome}\n`,
);
} catch (err) {
await onLog(
"stderr",
`[paperclip] Failed to inject Codex skill "${entry.name}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
`[paperclip] Failed to inject Codex skill "${entry.key}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
);
}
}

39
packages/adapters/codex-local/src/server/skills.ts
View File

@@ -53,7 +53,7 @@ async function readInstalledSkillTargets(skillsHome: string) {
async function buildCodexSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveCodexSkillsHome(config);
@@ -62,8 +62,8 @@ async function buildCodexSkillSnapshot(config: Record<string, unknown>): Promise
const warnings: string[] = [];
for (const available of availableEntries) {
const installedEntry = installed.get(available.name) ?? null;
const desired = desiredSet.has(available.name);
const installedEntry = installed.get(available.runtimeName) ?? null;
const desired = desiredSet.has(available.key);
let state: AdapterSkillEntry["state"] = "available";
let managed = false;
let detail: string | null = null;
@@ -82,12 +82,13 @@ async function buildCodexSkillSnapshot(config: Record<string, unknown>): Promise
}
entries.push({
name: available.name,
key: available.key,
runtimeName: available.runtimeName,
desired,
managed,
state,
sourcePath: available.source,
targetPath: path.join(skillsHome, available.name),
targetPath: path.join(skillsHome, available.runtimeName),
detail,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
@@ -95,23 +96,25 @@ async function buildCodexSkillSnapshot(config: Record<string, unknown>): Promise
}
for (const desiredSkill of desiredSkills) {
if (availableByName.has(desiredSkill)) continue;
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
name: desiredSkill,
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
sourcePath: null,
targetPath: path.join(skillsHome, desiredSkill),
targetPath: null,
detail: "Paperclip cannot find this skill in the local runtime skills directory.",
});
}
for (const [name, installedEntry] of installed.entries()) {
if (availableByName.has(name)) continue;
if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
entries.push({
name,
key: name,
runtimeName: name,
desired: false,
managed: false,
state: "external",
@@ -121,7 +124,7 @@ async function buildCodexSkillSnapshot(config: Record<string, unknown>): Promise
});
}
entries.sort((left, right) => left.name.localeCompare(right.name));
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
adapterType: "codex_local",
@@ -144,23 +147,23 @@ export async function syncCodexSkills(
const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
const desiredSet = new Set([
...desiredSkills,
...availableEntries.filter((entry) => entry.required).map((entry) => entry.name),
...availableEntries.filter((entry) => entry.required).map((entry) => entry.key),
]);
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]));
const availableByRuntimeName = new Map(availableEntries.map((entry) => [entry.runtimeName, entry]));
for (const available of availableEntries) {
if (!desiredSet.has(available.name)) continue;
const target = path.join(skillsHome, available.name);
if (!desiredSet.has(available.key)) continue;
const target = path.join(skillsHome, available.runtimeName);
await ensurePaperclipSkillSymlink(available.source, target);
}
for (const [name, installedEntry] of installed.entries()) {
const available = availableByName.get(name);
const available = availableByRuntimeName.get(name);
if (!available) continue;
if (desiredSet.has(name)) continue;
if (desiredSet.has(available.key)) continue;
if (installedEntry.targetPath !== available.source) continue;
await fs.unlink(path.join(skillsHome, name)).catch(() => {});
}
@@ -170,7 +173,7 @@ export async function syncCodexSkills(
export function resolveCodexDesiredSkillNames(
config: Record<string, unknown>,
availableEntries: Array<{ name: string; required?: boolean }>,
availableEntries: Array<{ key: string; required?: boolean }>,
) {
return resolvePaperclipDesiredSkillNames(config, availableEntries);
}

18
packages/adapters/cursor-local/src/server/execute.ts
View File

@@ -95,7 +95,7 @@ function cursorSkillsHome(): string {
type EnsureCursorSkillsInjectedOptions = {
skillsDir?: string | null;
skillsEntries?: Array<{ name: string; source: string }>;
skillsEntries?: Array<{ key: string; runtimeName: string; source: string }>;
skillsHome?: string;
linkSkill?: (source: string, target: string) => Promise<void>;
};
@@ -108,7 +108,11 @@ export async function ensureCursorSkillsInjected(
?? (options.skillsDir
? (await fs.readdir(options.skillsDir, { withFileTypes: true }))
.filter((entry) => entry.isDirectory())
.map((entry) => ({ name: entry.name, source: path.join(options.skillsDir!, entry.name) }))
.map((entry) => ({
key: entry.name,
runtimeName: entry.name,
source: path.join(options.skillsDir!, entry.name),
}))
: await readPaperclipRuntimeSkillEntries({}, __moduleDir));
if (skillsEntries.length === 0) return;
@@ -124,7 +128,7 @@ export async function ensureCursorSkillsInjected(
}
const removedSkills = await removeMaintainerOnlySkillSymlinks(
skillsHome,
skillsEntries.map((entry) => entry.name),
skillsEntries.map((entry) => entry.runtimeName),
);
for (const skillName of removedSkills) {
await onLog(
@@ -134,19 +138,19 @@ export async function ensureCursorSkillsInjected(
}
const linkSkill = options.linkSkill ?? ((source: string, target: string) => fs.symlink(source, target));
for (const entry of skillsEntries) {
const target = path.join(skillsHome, entry.name);
const target = path.join(skillsHome, entry.runtimeName);
try {
const result = await ensurePaperclipSkillSymlink(entry.source, target, linkSkill);
if (result === "skipped") continue;
await onLog(
"stderr",
`[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} Cursor skill "${entry.name}" into ${skillsHome}\n`,
`[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} Cursor skill "${entry.key}" into ${skillsHome}\n`,
);
} catch (err) {
await onLog(
"stderr",
`[paperclip] Failed to inject Cursor skill "${entry.name}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
`[paperclip] Failed to inject Cursor skill "${entry.key}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
);
}
}
@@ -183,7 +187,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
const cursorSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const desiredCursorSkillNames = resolvePaperclipDesiredSkillNames(config, cursorSkillEntries);
await ensureCursorSkillsInjected(onLog, {
skillsEntries: cursorSkillEntries.filter((entry) => desiredCursorSkillNames.includes(entry.name)),
skillsEntries: cursorSkillEntries.filter((entry) => desiredCursorSkillNames.includes(entry.key)),
});
const envConfig = parseObject(config.env);

39
packages/adapters/cursor-local/src/server/skills.ts
View File

@@ -53,7 +53,7 @@ async function readInstalledSkillTargets(skillsHome: string) {
async function buildCursorSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveCursorSkillsHome(config);
@@ -62,8 +62,8 @@ async function buildCursorSkillSnapshot(config: Record<string, unknown>): Promis
const warnings: string[] = [];
for (const available of availableEntries) {
const installedEntry = installed.get(available.name) ?? null;
const desired = desiredSet.has(available.name);
const installedEntry = installed.get(available.runtimeName) ?? null;
const desired = desiredSet.has(available.key);
let state: AdapterSkillEntry["state"] = "available";
let managed = false;
let detail: string | null = null;
@@ -82,12 +82,13 @@ async function buildCursorSkillSnapshot(config: Record<string, unknown>): Promis
}
entries.push({
name: available.name,
key: available.key,
runtimeName: available.runtimeName,
desired,
managed,
state,
sourcePath: available.source,
targetPath: path.join(skillsHome, available.name),
targetPath: path.join(skillsHome, available.runtimeName),
detail,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
@@ -95,23 +96,25 @@ async function buildCursorSkillSnapshot(config: Record<string, unknown>): Promis
}
for (const desiredSkill of desiredSkills) {
if (availableByName.has(desiredSkill)) continue;
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
name: desiredSkill,
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
sourcePath: null,
targetPath: path.join(skillsHome, desiredSkill),
targetPath: null,
detail: "Paperclip cannot find this skill in the local runtime skills directory.",
});
}
for (const [name, installedEntry] of installed.entries()) {
if (availableByName.has(name)) continue;
if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
entries.push({
name,
key: name,
runtimeName: name,
desired: false,
managed: false,
state: "external",
@@ -121,7 +124,7 @@ async function buildCursorSkillSnapshot(config: Record<string, unknown>): Promis
});
}
entries.sort((left, right) => left.name.localeCompare(right.name));
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
adapterType: "cursor",
@@ -144,23 +147,23 @@ export async function syncCursorSkills(
const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
const desiredSet = new Set([
...desiredSkills,
...availableEntries.filter((entry) => entry.required).map((entry) => entry.name),
...availableEntries.filter((entry) => entry.required).map((entry) => entry.key),
]);
const skillsHome = resolveCursorSkillsHome(ctx.config);
await fs.mkdir(skillsHome, { recursive: true });
const installed = await readInstalledSkillTargets(skillsHome);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const availableByRuntimeName = new Map(availableEntries.map((entry) => [entry.runtimeName, entry]));
for (const available of availableEntries) {
if (!desiredSet.has(available.name)) continue;
const target = path.join(skillsHome, available.name);
if (!desiredSet.has(available.key)) continue;
const target = path.join(skillsHome, available.runtimeName);
await ensurePaperclipSkillSymlink(available.source, target);
}
for (const [name, installedEntry] of installed.entries()) {
const available = availableByName.get(name);
const available = availableByRuntimeName.get(name);
if (!available) continue;
if (desiredSet.has(name)) continue;
if (desiredSet.has(available.key)) continue;
if (installedEntry.targetPath !== available.source) continue;
await fs.unlink(path.join(skillsHome, name)).catch(() => {});
}
@@ -170,7 +173,7 @@ export async function syncCursorSkills(
export function resolveCursorDesiredSkillNames(
config: Record<string, unknown>,
availableEntries: Array<{ name: string; required?: boolean }>,
availableEntries: Array<{ key: string; required?: boolean }>,
) {
return resolvePaperclipDesiredSkillNames(config, availableEntries);
}

14
packages/adapters/gemini-local/src/server/execute.ts
View File

@@ -85,11 +85,11 @@ function geminiSkillsHome(): string {
*/
async function ensureGeminiSkillsInjected(
onLog: AdapterExecutionContext["onLog"],
skillsEntries: Array<{ name: string; source: string }>,
skillsEntries: Array<{ key: string; runtimeName: string; source: string }>,
desiredSkillNames?: string[],
): Promise<void> {
const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.name));
const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.name));
const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.key));
const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.key));
if (selectedEntries.length === 0) return;
const skillsHome = geminiSkillsHome();
@@ -104,7 +104,7 @@ async function ensureGeminiSkillsInjected(
}
const removedSkills = await removeMaintainerOnlySkillSymlinks(
skillsHome,
selectedEntries.map((entry) => entry.name),
selectedEntries.map((entry) => entry.runtimeName),
);
for (const skillName of removedSkills) {
await onLog(
@@ -114,19 +114,19 @@ async function ensureGeminiSkillsInjected(
}
for (const entry of selectedEntries) {
const target = path.join(skillsHome, entry.name);
const target = path.join(skillsHome, entry.runtimeName);
try {
const result = await ensurePaperclipSkillSymlink(entry.source, target);
if (result === "skipped") continue;
await onLog(
"stderr",
`[paperclip] ${result === "repaired" ? "Repaired" : "Linked"} Gemini skill: ${entry.name}\n`,
`[paperclip] ${result === "repaired" ? "Repaired" : "Linked"} Gemini skill: ${entry.key}\n`,
);
} catch (err) {
await onLog(
"stderr",
`[paperclip] Failed to link Gemini skill "${entry.name}": ${err instanceof Error ? err.message : String(err)}\n`,
`[paperclip] Failed to link Gemini skill "${entry.key}": ${err instanceof Error ? err.message : String(err)}\n`,
);
}
}

39
packages/adapters/gemini-local/src/server/skills.ts
View File

@@ -53,7 +53,7 @@ async function readInstalledSkillTargets(skillsHome: string) {
async function buildGeminiSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveGeminiSkillsHome(config);
@@ -62,8 +62,8 @@ async function buildGeminiSkillSnapshot(config: Record<string, unknown>): Promis
const warnings: string[] = [];
for (const available of availableEntries) {
const installedEntry = installed.get(available.name) ?? null;
const desired = desiredSet.has(available.name);
const installedEntry = installed.get(available.runtimeName) ?? null;
const desired = desiredSet.has(available.key);
let state: AdapterSkillEntry["state"] = "available";
let managed = false;
let detail: string | null = null;
@@ -82,12 +82,13 @@ async function buildGeminiSkillSnapshot(config: Record<string, unknown>): Promis
}
entries.push({
name: available.name,
key: available.key,
runtimeName: available.runtimeName,
desired,
managed,
state,
sourcePath: available.source,
targetPath: path.join(skillsHome, available.name),
targetPath: path.join(skillsHome, available.runtimeName),
detail,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
@@ -95,23 +96,25 @@ async function buildGeminiSkillSnapshot(config: Record<string, unknown>): Promis
}
for (const desiredSkill of desiredSkills) {
if (availableByName.has(desiredSkill)) continue;
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
name: desiredSkill,
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
sourcePath: null,
targetPath: path.join(skillsHome, desiredSkill),
targetPath: null,
detail: "Paperclip cannot find this skill in the local runtime skills directory.",
});
}
for (const [name, installedEntry] of installed.entries()) {
if (availableByName.has(name)) continue;
if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
entries.push({
name,
key: name,
runtimeName: name,
desired: false,
managed: false,
state: "external",
@@ -121,7 +124,7 @@ async function buildGeminiSkillSnapshot(config: Record<string, unknown>): Promis
});
}
entries.sort((left, right) => left.name.localeCompare(right.name));
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
adapterType: "gemini_local",
@@ -144,23 +147,23 @@ export async function syncGeminiSkills(
const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
const desiredSet = new Set([
...desiredSkills,
...availableEntries.filter((entry) => entry.required).map((entry) => entry.name),
...availableEntries.filter((entry) => entry.required).map((entry) => entry.key),
]);
const skillsHome = resolveGeminiSkillsHome(ctx.config);
await fs.mkdir(skillsHome, { recursive: true });
const installed = await readInstalledSkillTargets(skillsHome);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const availableByRuntimeName = new Map(availableEntries.map((entry) => [entry.runtimeName, entry]));
for (const available of availableEntries) {
if (!desiredSet.has(available.name)) continue;
const target = path.join(skillsHome, available.name);
if (!desiredSet.has(available.key)) continue;
const target = path.join(skillsHome, available.runtimeName);
await ensurePaperclipSkillSymlink(available.source, target);
}
for (const [name, installedEntry] of installed.entries()) {
const available = availableByName.get(name);
const available = availableByRuntimeName.get(name);
if (!available) continue;
if (desiredSet.has(name)) continue;
if (desiredSet.has(available.key)) continue;
if (installedEntry.targetPath !== available.source) continue;
await fs.unlink(path.join(skillsHome, name)).catch(() => {});
}
@@ -170,7 +173,7 @@ export async function syncGeminiSkills(
export function resolveGeminiDesiredSkillNames(
config: Record<string, unknown>,
availableEntries: Array<{ name: string; required?: boolean }>,
availableEntries: Array<{ key: string; required?: boolean }>,
) {
return resolvePaperclipDesiredSkillNames(config, availableEntries);
}

14
packages/adapters/opencode-local/src/server/execute.ts
View File

@@ -52,16 +52,16 @@ function claudeSkillsHome(): string {
async function ensureOpenCodeSkillsInjected(
onLog: AdapterExecutionContext["onLog"],
skillsEntries: Array<{ name: string; source: string }>,
skillsEntries: Array<{ key: string; runtimeName: string; source: string }>,
desiredSkillNames?: string[],
) {
const skillsHome = claudeSkillsHome();
await fs.mkdir(skillsHome, { recursive: true });
const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.name));
const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.name));
const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.key));
const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.key));
const removedSkills = await removeMaintainerOnlySkillSymlinks(
skillsHome,
selectedEntries.map((entry) => entry.name),
selectedEntries.map((entry) => entry.runtimeName),
);
for (const skillName of removedSkills) {
await onLog(
@@ -70,19 +70,19 @@ async function ensureOpenCodeSkillsInjected(
);
}
for (const entry of selectedEntries) {
const target = path.join(skillsHome, entry.name);
const target = path.join(skillsHome, entry.runtimeName);
try {
const result = await ensurePaperclipSkillSymlink(entry.source, target);
if (result === "skipped") continue;
await onLog(
"stderr",
`[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} OpenCode skill "${entry.name}" into ${skillsHome}\n`,
`[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} OpenCode skill "${entry.key}" into ${skillsHome}\n`,
);
} catch (err) {
await onLog(
"stderr",
`[paperclip] Failed to inject OpenCode skill "${entry.name}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
`[paperclip] Failed to inject OpenCode skill "${entry.key}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
);
}
}

39
packages/adapters/opencode-local/src/server/skills.ts
View File

@@ -53,7 +53,7 @@ async function readInstalledSkillTargets(skillsHome: string) {
async function buildOpenCodeSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveOpenCodeSkillsHome(config);
@@ -64,8 +64,8 @@ async function buildOpenCodeSkillSnapshot(config: Record<string, unknown>): Prom
];
for (const available of availableEntries) {
const installedEntry = installed.get(available.name) ?? null;
const desired = desiredSet.has(available.name);
const installedEntry = installed.get(available.runtimeName) ?? null;
const desired = desiredSet.has(available.key);
let state: AdapterSkillEntry["state"] = "available";
let managed = false;
let detail: string | null = null;
@@ -85,12 +85,13 @@ async function buildOpenCodeSkillSnapshot(config: Record<string, unknown>): Prom
}
entries.push({
name: available.name,
key: available.key,
runtimeName: available.runtimeName,
desired,
managed,
state,
sourcePath: available.source,
targetPath: path.join(skillsHome, available.name),
targetPath: path.join(skillsHome, available.runtimeName),
detail,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
@@ -98,23 +99,25 @@ async function buildOpenCodeSkillSnapshot(config: Record<string, unknown>): Prom
}
for (const desiredSkill of desiredSkills) {
if (availableByName.has(desiredSkill)) continue;
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
name: desiredSkill,
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
sourcePath: null,
targetPath: path.join(skillsHome, desiredSkill),
targetPath: null,
detail: "Paperclip cannot find this skill in the local runtime skills directory.",
});
}
for (const [name, installedEntry] of installed.entries()) {
if (availableByName.has(name)) continue;
if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
entries.push({
name,
key: name,
runtimeName: name,
desired: false,
managed: false,
state: "external",
@@ -124,7 +127,7 @@ async function buildOpenCodeSkillSnapshot(config: Record<string, unknown>): Prom
});
}
entries.sort((left, right) => left.name.localeCompare(right.name));
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
adapterType: "opencode_local",
@@ -147,23 +150,23 @@ export async function syncOpenCodeSkills(
const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
const desiredSet = new Set([
...desiredSkills,
...availableEntries.filter((entry) => entry.required).map((entry) => entry.name),
...availableEntries.filter((entry) => entry.required).map((entry) => entry.key),
]);
const skillsHome = resolveOpenCodeSkillsHome(ctx.config);
await fs.mkdir(skillsHome, { recursive: true });
const installed = await readInstalledSkillTargets(skillsHome);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const availableByRuntimeName = new Map(availableEntries.map((entry) => [entry.runtimeName, entry]));
for (const available of availableEntries) {
if (!desiredSet.has(available.name)) continue;
const target = path.join(skillsHome, available.name);
if (!desiredSet.has(available.key)) continue;
const target = path.join(skillsHome, available.runtimeName);
await ensurePaperclipSkillSymlink(available.source, target);
}
for (const [name, installedEntry] of installed.entries()) {
const available = availableByName.get(name);
const available = availableByRuntimeName.get(name);
if (!available) continue;
if (desiredSet.has(name)) continue;
if (desiredSet.has(available.key)) continue;
if (installedEntry.targetPath !== available.source) continue;
await fs.unlink(path.join(skillsHome, name)).catch(() => {});
}
@@ -173,7 +176,7 @@ export async function syncOpenCodeSkills(
export function resolveOpenCodeDesiredSkillNames(
config: Record<string, unknown>,
availableEntries: Array<{ name: string; required?: boolean }>,
availableEntries: Array<{ key: string; required?: boolean }>,
) {
return resolvePaperclipDesiredSkillNames(config, availableEntries);
}

14
packages/adapters/pi-local/src/server/execute.ts
View File

@@ -53,17 +53,17 @@ function parseModelId(model: string | null): string | null {
async function ensurePiSkillsInjected(
onLog: AdapterExecutionContext["onLog"],
skillsEntries: Array<{ name: string; source: string }>,
skillsEntries: Array<{ key: string; runtimeName: string; source: string }>,
desiredSkillNames?: string[],
) {
const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.name));
const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.name));
const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.key));
const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.key));
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,
selectedEntries.map((entry) => entry.name),
selectedEntries.map((entry) => entry.runtimeName),
);
for (const skillName of removedSkills) {
await onLog(
@@ -73,19 +73,19 @@ async function ensurePiSkillsInjected(
}
for (const entry of selectedEntries) {
const target = path.join(piSkillsHome, entry.name);
const target = path.join(piSkillsHome, entry.runtimeName);
try {
const result = await ensurePaperclipSkillSymlink(entry.source, target);
if (result === "skipped") continue;
await onLog(
"stderr",
`[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} Pi skill "${entry.name}" into ${piSkillsHome}\n`,
`[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} Pi skill "${entry.key}" into ${piSkillsHome}\n`,
);
} catch (err) {
await onLog(
"stderr",
`[paperclip] Failed to inject Pi skill "${entry.name}" into ${piSkillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
`[paperclip] Failed to inject Pi skill "${entry.key}" into ${piSkillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
);
}
}

39
packages/adapters/pi-local/src/server/skills.ts
View File

@@ -53,7 +53,7 @@ async function readInstalledSkillTargets(skillsHome: string) {
async function buildPiSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolvePiSkillsHome(config);
@@ -62,8 +62,8 @@ async function buildPiSkillSnapshot(config: Record<string, unknown>): Promise<Ad
const warnings: string[] = [];
for (const available of availableEntries) {
const installedEntry = installed.get(available.name) ?? null;
const desired = desiredSet.has(available.name);
const installedEntry = installed.get(available.runtimeName) ?? null;
const desired = desiredSet.has(available.key);
let state: AdapterSkillEntry["state"] = "available";
let managed = false;
let detail: string | null = null;
@@ -82,12 +82,13 @@ async function buildPiSkillSnapshot(config: Record<string, unknown>): Promise<Ad
}
entries.push({
name: available.name,
key: available.key,
runtimeName: available.runtimeName,
desired,
managed,
state,
sourcePath: available.source,
targetPath: path.join(skillsHome, available.name),
targetPath: path.join(skillsHome, available.runtimeName),
detail,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
@@ -95,23 +96,25 @@ async function buildPiSkillSnapshot(config: Record<string, unknown>): Promise<Ad
}
for (const desiredSkill of desiredSkills) {
if (availableByName.has(desiredSkill)) continue;
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
name: desiredSkill,
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
sourcePath: null,
targetPath: path.join(skillsHome, desiredSkill),
targetPath: null,
detail: "Paperclip cannot find this skill in the local runtime skills directory.",
});
}
for (const [name, installedEntry] of installed.entries()) {
if (availableByName.has(name)) continue;
if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
entries.push({
name,
key: name,
runtimeName: name,
desired: false,
managed: false,
state: "external",
@@ -121,7 +124,7 @@ async function buildPiSkillSnapshot(config: Record<string, unknown>): Promise<Ad
});
}
entries.sort((left, right) => left.name.localeCompare(right.name));
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
adapterType: "pi_local",
@@ -144,23 +147,23 @@ export async function syncPiSkills(
const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
const desiredSet = new Set([
...desiredSkills,
...availableEntries.filter((entry) => entry.required).map((entry) => entry.name),
...availableEntries.filter((entry) => entry.required).map((entry) => entry.key),
]);
const skillsHome = resolvePiSkillsHome(ctx.config);
await fs.mkdir(skillsHome, { recursive: true });
const installed = await readInstalledSkillTargets(skillsHome);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const availableByRuntimeName = new Map(availableEntries.map((entry) => [entry.runtimeName, entry]));
for (const available of availableEntries) {
if (!desiredSet.has(available.name)) continue;
const target = path.join(skillsHome, available.name);
if (!desiredSet.has(available.key)) continue;
const target = path.join(skillsHome, available.runtimeName);
await ensurePaperclipSkillSymlink(available.source, target);
}
for (const [name, installedEntry] of installed.entries()) {
const available = availableByName.get(name);
const available = availableByRuntimeName.get(name);
if (!available) continue;
if (desiredSet.has(name)) continue;
if (desiredSet.has(available.key)) continue;
if (installedEntry.targetPath !== available.source) continue;
await fs.unlink(path.join(skillsHome, name)).catch(() => {});
}
@@ -170,7 +173,7 @@ export async function syncPiSkills(
export function resolvePiDesiredSkillNames(
config: Record<string, unknown>,
availableEntries: Array<{ name: string; required?: boolean }>,
availableEntries: Array<{ key: string; required?: boolean }>,
) {
return resolvePaperclipDesiredSkillNames(config, availableEntries);
}

27
packages/db/src/migrations/0035_colorful_rhino.sql Normal file
View File

@@ -0,0 +1,27 @@
ALTER TABLE "company_skills" ADD COLUMN "key" text;--> statement-breakpoint
UPDATE "company_skills"
SET "key" = CASE
WHEN COALESCE("metadata"->>'sourceKind', '') = 'paperclip_bundled' THEN 'paperclipai/paperclip/' || "slug"
WHEN (COALESCE("metadata"->>'sourceKind', '') = 'github' OR "source_type" = 'github')
AND COALESCE("metadata"->>'owner', '') <> ''
AND COALESCE("metadata"->>'repo', '') <> ''
THEN lower("metadata"->>'owner') || '/' || lower("metadata"->>'repo') || '/' || "slug"
WHEN COALESCE("metadata"->>'sourceKind', '') = 'managed_local' THEN 'company/' || "company_id"::text || '/' || "slug"
WHEN (COALESCE("metadata"->>'sourceKind', '') = 'url' OR "source_type" = 'url')
THEN 'url/'
|| COALESCE(
NULLIF(regexp_replace(lower(regexp_replace(COALESCE("source_locator", ''), '^https?://([^/]+).*$','\1')), '[^a-z0-9._-]+', '-', 'g'), ''),
'unknown'
)
|| '/'
|| substr(md5(COALESCE("source_locator", "slug")), 1, 10)
|| '/'
|| "slug"
WHEN "source_type" = 'local_path' AND COALESCE("source_locator", '') <> ''
THEN 'local/' || substr(md5("source_locator"), 1, 10) || '/' || "slug"
ELSE 'company/' || "company_id"::text || '/' || "slug"
END
WHERE "key" IS NULL;--> statement-breakpoint
ALTER TABLE "company_skills" ALTER COLUMN "key" SET NOT NULL;--> statement-breakpoint
DROP INDEX IF EXISTS "company_skills_company_slug_idx";--> statement-breakpoint
CREATE UNIQUE INDEX "company_skills_company_key_idx" ON "company_skills" USING btree ("company_id","key");

9212
packages/db/src/migrations/meta/0035_snapshot.json Normal file
View File

File diff suppressed because it is too large Load Diff

7
packages/db/src/migrations/meta/_journal.json
View File

@@ -246,6 +246,13 @@
"when": 1773697572188,
"tag": "0034_fat_dormammu",
"breakpoints": true
},
{
"idx": 35,
"version": "7",
"when": 1773703213570,
"tag": "0035_colorful_rhino",
"breakpoints": true
}
]
}

3
packages/db/src/schema/company_skills.ts
View File

@@ -14,6 +14,7 @@ export const companySkills = pgTable(
{
id: uuid("id").primaryKey().defaultRandom(),
companyId: uuid("company_id").notNull().references(() => companies.id),
key: text("key").notNull(),
slug: text("slug").notNull(),
name: text("name").notNull(),
description: text("description"),
@@ -29,7 +30,7 @@ export const companySkills = pgTable(
updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
},
(table) => ({
companySlugUniqueIdx: uniqueIndex("company_skills_company_slug_idx").on(table.companyId, table.slug),
companyKeyUniqueIdx: uniqueIndex("company_skills_company_key_idx").on(table.companyId, table.key),
companyNameIdx: index("company_skills_company_name_idx").on(table.companyId, table.name),
}),
);

3
packages/shared/src/types/adapter-skills.ts
View File

@@ -9,7 +9,8 @@ export type AgentSkillState =
| "external";
export interface AgentSkillEntry {
name: string;
key: string;
runtimeName: string | null;
desired: boolean;
managed: boolean;
required?: boolean;

1
packages/shared/src/types/company-portability.ts
View File

@@ -74,6 +74,7 @@ export interface CompanyPortabilityAgentManifestEntry {
}
export interface CompanyPortabilitySkillManifestEntry {
key: string;
slug: string;
name: string;
path: string;

2
packages/shared/src/types/company-skill.ts
View File

@@ -14,6 +14,7 @@ export interface CompanySkillFileInventoryEntry {
export interface CompanySkill {
id: string;
companyId: string;
key: string;
slug: string;
name: string;
description: string | null;
@@ -32,6 +33,7 @@ export interface CompanySkill {
export interface CompanySkillListItem {
id: string;
companyId: string;
key: string;
slug: string;
name: string;
description: string | null;

3
packages/shared/src/validators/adapter-skills.ts
View File

@@ -16,7 +16,8 @@ export const agentSkillSyncModeSchema = z.enum([
]);
export const agentSkillEntrySchema = z.object({
name: z.string().min(1),
key: z.string().min(1),
runtimeName: z.string().min(1).nullable(),
desired: z.boolean(),
managed: z.boolean(),
required: z.boolean().optional(),

1
packages/shared/src/validators/company-portability.ts
View File

@@ -46,6 +46,7 @@ export const portabilityAgentManifestEntrySchema = z.object({
});
export const portabilitySkillManifestEntrySchema = z.object({
key: z.string().min(1),
slug: z.string().min(1),
name: z.string().min(1),
path: z.string().min(1),

1
packages/shared/src/validators/company-skill.ts
View File

@@ -13,6 +13,7 @@ export const companySkillFileInventoryEntrySchema = z.object({
export const companySkillSchema = z.object({
id: z.string().uuid(),
companyId: z.string().uuid(),
key: z.string().min(1),
slug: z.string().min(1),
name: z.string().min(1),
description: z.string().nullable(),

19
server/src/__tests__/claude-local-skill-sync.test.ts
View File

@@ -5,6 +5,9 @@ import {
} from "@paperclipai/adapter-claude-local/server";
describe("claude local skill sync", () => {
const paperclipKey = "paperclipai/paperclip/paperclip";
const createAgentKey = "paperclipai/paperclip/paperclip-create-agent";
it("defaults to mounting all built-in Paperclip skills when no explicit selection exists", async () => {
const snapshot = await listClaudeSkills({
agentId: "agent-1",
@@ -15,9 +18,9 @@ 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");
expect(snapshot.desiredSkills).toContain(paperclipKey);
expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.required).toBe(true);
expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("configured");
});
it("respects an explicit desired skill list without mutating a persistent home", async () => {
@@ -27,13 +30,13 @@ describe("claude local skill sync", () => {
adapterType: "claude_local",
config: {
paperclipSkillSync: {
desiredSkills: ["paperclip"],
desiredSkills: [paperclipKey],
},
},
}, ["paperclip"]);
}, [paperclipKey]);
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("configured");
expect(snapshot.desiredSkills).toContain(paperclipKey);
expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("configured");
expect(snapshot.entries.find((entry) => entry.key === createAgentKey)?.state).toBe("configured");
});
});

15
server/src/__tests__/codex-local-skill-injection.test.ts
View File

@@ -31,6 +31,7 @@ async function createCustomSkill(root: string, skillName: string) {
}
describe("codex local adapter skill injection", () => {
const paperclipKey = "paperclipai/paperclip/paperclip";
const cleanupDirs = new Set<string>();
afterEach(async () => {
@@ -57,14 +58,18 @@ describe("codex local adapter skill injection", () => {
},
{
skillsHome,
skillsEntries: [{ name: "paperclip", source: path.join(currentRepo, "skills", "paperclip") }],
skillsEntries: [{
key: paperclipKey,
runtimeName: "paperclip",
source: path.join(currentRepo, "skills", "paperclip"),
}],
},
);
expect(await fs.realpath(path.join(skillsHome, "paperclip"))).toBe(
await fs.realpath(path.join(currentRepo, "skills", "paperclip")),
);
expect(logs.some((line) => line.includes('Repaired Codex skill "paperclip"'))).toBe(true);
expect(logs.some((line) => line.includes("Repaired Codex skill"))).toBe(true);
});
it("preserves a custom Codex skill symlink outside Paperclip repo checkouts", async () => {
@@ -81,7 +86,11 @@ describe("codex local adapter skill injection", () => {
await ensureCodexSkillsInjected(async () => {}, {
skillsHome,
skillsEntries: [{ name: "paperclip", source: path.join(currentRepo, "skills", "paperclip") }],
skillsEntries: [{
key: paperclipKey,
runtimeName: "paperclip",
source: path.join(currentRepo, "skills", "paperclip"),
}],
});
expect(await fs.realpath(path.join(skillsHome, "paperclip"))).toBe(

21
server/src/__tests__/codex-local-skill-sync.test.ts
View File

@@ -12,6 +12,7 @@ async function makeTempDir(prefix: string): Promise<string> {
}
describe("codex local skill sync", () => {
const paperclipKey = "paperclipai/paperclip/paperclip";
const cleanupDirs = new Set<string>();
afterEach(async () => {
@@ -32,19 +33,19 @@ describe("codex local skill sync", () => {
CODEX_HOME: codexHome,
},
paperclipSkillSync: {
desiredSkills: ["paperclip"],
desiredSkills: [paperclipKey],
},
},
} as const;
const before = await listCodexSkills(ctx);
expect(before.mode).toBe("persistent");
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");
expect(before.desiredSkills).toContain(paperclipKey);
expect(before.entries.find((entry) => entry.key === paperclipKey)?.required).toBe(true);
expect(before.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("missing");
const after = await syncCodexSkills(ctx, ["paperclip"]);
expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");
const after = await syncCodexSkills(ctx, [paperclipKey]);
expect(after.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("installed");
expect((await fs.lstat(path.join(codexHome, "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
@@ -61,12 +62,12 @@ describe("codex local skill sync", () => {
CODEX_HOME: codexHome,
},
paperclipSkillSync: {
desiredSkills: ["paperclip"],
desiredSkills: [paperclipKey],
},
},
} as const;
await syncCodexSkills(configuredCtx, ["paperclip"]);
await syncCodexSkills(configuredCtx, [paperclipKey]);
const clearedCtx = {
...configuredCtx,
@@ -81,8 +82,8 @@ describe("codex local skill sync", () => {
} as const;
const after = await syncCodexSkills(clearedCtx, []);
expect(after.desiredSkills).toContain("paperclip");
expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");
expect(after.desiredSkills).toContain(paperclipKey);
expect(after.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("installed");
expect((await fs.lstat(path.join(codexHome, "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
});

27
server/src/__tests__/company-portability.test.ts
View File

@@ -63,6 +63,9 @@ vi.mock("../services/company-skills.js", () => ({
const { companyPortabilityService } = await import("../services/company-portability.js");
describe("company portability", () => {
const paperclipKey = "paperclipai/paperclip/paperclip";
const companyPlaybookKey = "company/company-1/company-playbook";
beforeEach(() => {
vi.clearAllMocks();
companySvc.getById.mockResolvedValue({
@@ -86,7 +89,7 @@ describe("company portability", () => {
adapterConfig: {
promptTemplate: "You are ClaudeCoder.",
paperclipSkillSync: {
desiredSkills: ["paperclip"],
desiredSkills: [paperclipKey],
},
instructionsFilePath: "/tmp/ignored.md",
cwd: "/tmp/ignored",
@@ -153,6 +156,7 @@ describe("company portability", () => {
{
id: "skill-1",
companyId: "company-1",
key: paperclipKey,
slug: "paperclip",
name: "paperclip",
description: "Paperclip coordination skill",
@@ -178,6 +182,7 @@ describe("company portability", () => {
{
id: "skill-2",
companyId: "company-1",
key: companyPlaybookKey,
slug: "company-playbook",
name: "company-playbook",
description: "Internal company skill",
@@ -244,13 +249,13 @@ describe("company portability", () => {
expect(exported.files["COMPANY.md"]).toContain('schema: "agentcompanies/v1"');
expect(exported.files["agents/claudecoder/AGENTS.md"]).toContain("You are ClaudeCoder.");
expect(exported.files["agents/claudecoder/AGENTS.md"]).toContain("skills:");
expect(exported.files["agents/claudecoder/AGENTS.md"]).toContain('- "paperclip"');
expect(exported.files["agents/claudecoder/AGENTS.md"]).toContain(`- "${paperclipKey}"`);
expect(exported.files["agents/cmo/AGENTS.md"]).not.toContain("skills:");
expect(exported.files["skills/paperclip/SKILL.md"]).toContain("metadata:");
expect(exported.files["skills/paperclip/SKILL.md"]).toContain('kind: "github-dir"');
expect(exported.files["skills/paperclip/references/api.md"]).toBeUndefined();
expect(exported.files["skills/company-playbook/SKILL.md"]).toContain("# Company Playbook");
expect(exported.files["skills/company-playbook/references/checklist.md"]).toContain("# Checklist");
expect(exported.files[`skills/${paperclipKey}/SKILL.md`]).toContain("metadata:");
expect(exported.files[`skills/${paperclipKey}/SKILL.md`]).toContain('kind: "github-dir"');
expect(exported.files[`skills/${paperclipKey}/references/api.md`]).toBeUndefined();
expect(exported.files[`skills/${companyPlaybookKey}/SKILL.md`]).toContain("# Company Playbook");
expect(exported.files[`skills/${companyPlaybookKey}/references/checklist.md`]).toContain("# Checklist");
const extension = exported.files[".paperclip.yaml"];
expect(extension).toContain('schema: "paperclip/v1"');
@@ -284,9 +289,9 @@ describe("company portability", () => {
expandReferencedSkills: true,
});
expect(exported.files["skills/paperclip/SKILL.md"]).toContain("# Paperclip");
expect(exported.files["skills/paperclip/SKILL.md"]).toContain("metadata:");
expect(exported.files["skills/paperclip/references/api.md"]).toContain("# API");
expect(exported.files[`skills/${paperclipKey}/SKILL.md`]).toContain("# Paperclip");
expect(exported.files[`skills/${paperclipKey}/SKILL.md`]).toContain("metadata:");
expect(exported.files[`skills/${paperclipKey}/references/api.md`]).toContain("# API");
});
it("reads env inputs back from .paperclip.yaml during preview import", async () => {
@@ -392,7 +397,7 @@ describe("company portability", () => {
expect(agentSvc.create).toHaveBeenCalledWith("company-imported", expect.objectContaining({
adapterConfig: expect.objectContaining({
paperclipSkillSync: {
desiredSkills: ["paperclip"],
desiredSkills: [paperclipKey],
},
}),
}));

31
server/src/__tests__/cursor-local-skill-sync.test.ts
View File

@@ -19,6 +19,7 @@ async function createSkillDir(root: string, name: string) {
}
describe("cursor local skill sync", () => {
const paperclipKey = "paperclipai/paperclip/paperclip";
const cleanupDirs = new Set<string>();
afterEach(async () => {
@@ -39,19 +40,19 @@ describe("cursor local skill sync", () => {
HOME: home,
},
paperclipSkillSync: {
desiredSkills: ["paperclip"],
desiredSkills: [paperclipKey],
},
},
} as const;
const before = await listCursorSkills(ctx);
expect(before.mode).toBe("persistent");
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");
expect(before.desiredSkills).toContain(paperclipKey);
expect(before.entries.find((entry) => entry.key === paperclipKey)?.required).toBe(true);
expect(before.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("missing");
const after = await syncCursorSkills(ctx, ["paperclip"]);
expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");
const after = await syncCursorSkills(ctx, [paperclipKey]);
expect(after.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("installed");
expect((await fs.lstat(path.join(home, ".cursor", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
@@ -74,13 +75,15 @@ describe("cursor local skill sync", () => {
},
paperclipRuntimeSkills: [
{
name: "paperclip",
key: "paperclip",
runtimeName: "paperclip",
source: paperclipDir,
required: true,
requiredReason: "Bundled Paperclip skills are always available for local adapters.",
},
{
name: "ascii-heart",
key: "ascii-heart",
runtimeName: "ascii-heart",
source: asciiHeartDir,
},
],
@@ -93,11 +96,11 @@ describe("cursor local skill sync", () => {
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");
expect(before.entries.find((entry) => entry.key === "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(after.entries.find((entry) => entry.key === "ascii-heart")?.state).toBe("installed");
expect((await fs.lstat(path.join(home, ".cursor", "skills", "ascii-heart"))).isSymbolicLink()).toBe(true);
});
@@ -114,12 +117,12 @@ describe("cursor local skill sync", () => {
HOME: home,
},
paperclipSkillSync: {
desiredSkills: ["paperclip"],
desiredSkills: [paperclipKey],
},
},
} as const;
await syncCursorSkills(configuredCtx, ["paperclip"]);
await syncCursorSkills(configuredCtx, [paperclipKey]);
const clearedCtx = {
...configuredCtx,
@@ -134,8 +137,8 @@ describe("cursor local skill sync", () => {
} as const;
const after = await syncCursorSkills(clearedCtx, []);
expect(after.desiredSkills).toContain("paperclip");
expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");
expect(after.desiredSkills).toContain(paperclipKey);
expect(after.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("installed");
expect((await fs.lstat(path.join(home, ".cursor", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
});

21
server/src/__tests__/gemini-local-skill-sync.test.ts
View File

@@ -12,6 +12,7 @@ async function makeTempDir(prefix: string): Promise<string> {
}
describe("gemini local skill sync", () => {
const paperclipKey = "paperclipai/paperclip/paperclip";
const cleanupDirs = new Set<string>();
afterEach(async () => {
@@ -32,19 +33,19 @@ describe("gemini local skill sync", () => {
HOME: home,
},
paperclipSkillSync: {
desiredSkills: ["paperclip"],
desiredSkills: [paperclipKey],
},
},
} as const;
const before = await listGeminiSkills(ctx);
expect(before.mode).toBe("persistent");
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");
expect(before.desiredSkills).toContain(paperclipKey);
expect(before.entries.find((entry) => entry.key === paperclipKey)?.required).toBe(true);
expect(before.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("missing");
const after = await syncGeminiSkills(ctx, ["paperclip"]);
expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");
const after = await syncGeminiSkills(ctx, [paperclipKey]);
expect(after.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("installed");
expect((await fs.lstat(path.join(home, ".gemini", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
@@ -61,12 +62,12 @@ describe("gemini local skill sync", () => {
HOME: home,
},
paperclipSkillSync: {
desiredSkills: ["paperclip"],
desiredSkills: [paperclipKey],
},
},
} as const;
await syncGeminiSkills(configuredCtx, ["paperclip"]);
await syncGeminiSkills(configuredCtx, [paperclipKey]);
const clearedCtx = {
...configuredCtx,
@@ -81,8 +82,8 @@ describe("gemini local skill sync", () => {
} as const;
const after = await syncGeminiSkills(clearedCtx, []);
expect(after.desiredSkills).toContain("paperclip");
expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");
expect(after.desiredSkills).toContain(paperclipKey);
expect(after.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("installed");
expect((await fs.lstat(path.join(home, ".gemini", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
});

21
server/src/__tests__/opencode-local-skill-sync.test.ts
View File

@@ -12,6 +12,7 @@ async function makeTempDir(prefix: string): Promise<string> {
}
describe("opencode local skill sync", () => {
const paperclipKey = "paperclipai/paperclip/paperclip";
const cleanupDirs = new Set<string>();
afterEach(async () => {
@@ -32,7 +33,7 @@ describe("opencode local skill sync", () => {
HOME: home,
},
paperclipSkillSync: {
desiredSkills: ["paperclip"],
desiredSkills: [paperclipKey],
},
},
} as const;
@@ -40,12 +41,12 @@ 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).toContain("paperclip");
expect(before.entries.find((entry) => entry.name === "paperclip")?.required).toBe(true);
expect(before.entries.find((entry) => entry.name === "paperclip")?.state).toBe("missing");
expect(before.desiredSkills).toContain(paperclipKey);
expect(before.entries.find((entry) => entry.key === paperclipKey)?.required).toBe(true);
expect(before.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("missing");
const after = await syncOpenCodeSkills(ctx, ["paperclip"]);
expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");
const after = await syncOpenCodeSkills(ctx, [paperclipKey]);
expect(after.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("installed");
expect((await fs.lstat(path.join(home, ".claude", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
@@ -62,12 +63,12 @@ describe("opencode local skill sync", () => {
HOME: home,
},
paperclipSkillSync: {
desiredSkills: ["paperclip"],
desiredSkills: [paperclipKey],
},
},
} as const;
await syncOpenCodeSkills(configuredCtx, ["paperclip"]);
await syncOpenCodeSkills(configuredCtx, [paperclipKey]);
const clearedCtx = {
...configuredCtx,
@@ -82,8 +83,8 @@ describe("opencode local skill sync", () => {
} as const;
const after = await syncOpenCodeSkills(clearedCtx, []);
expect(after.desiredSkills).toContain("paperclip");
expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");
expect(after.desiredSkills).toContain(paperclipKey);
expect(after.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("installed");
expect((await fs.lstat(path.join(home, ".claude", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
});

3
server/src/__tests__/paperclip-skill-utils.test.ts
View File

@@ -30,7 +30,8 @@ describe("paperclip skill utils", () => {
const entries = await listPaperclipSkillEntries(moduleDir);
expect(entries.map((entry) => entry.name)).toEqual(["paperclip"]);
expect(entries.map((entry) => entry.key)).toEqual(["paperclipai/paperclip/paperclip"]);
expect(entries.map((entry) => entry.runtimeName)).toEqual(["paperclip"]);
expect(entries[0]?.source).toBe(path.join(root, "skills", "paperclip"));
});

21
server/src/__tests__/pi-local-skill-sync.test.ts
View File

@@ -12,6 +12,7 @@ async function makeTempDir(prefix: string): Promise<string> {
}
describe("pi local skill sync", () => {
const paperclipKey = "paperclipai/paperclip/paperclip";
const cleanupDirs = new Set<string>();
afterEach(async () => {
@@ -32,19 +33,19 @@ describe("pi local skill sync", () => {
HOME: home,
},
paperclipSkillSync: {
desiredSkills: ["paperclip"],
desiredSkills: [paperclipKey],
},
},
} as const;
const before = await listPiSkills(ctx);
expect(before.mode).toBe("persistent");
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");
expect(before.desiredSkills).toContain(paperclipKey);
expect(before.entries.find((entry) => entry.key === paperclipKey)?.required).toBe(true);
expect(before.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("missing");
const after = await syncPiSkills(ctx, ["paperclip"]);
expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");
const after = await syncPiSkills(ctx, [paperclipKey]);
expect(after.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("installed");
expect((await fs.lstat(path.join(home, ".pi", "agent", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
@@ -61,12 +62,12 @@ describe("pi local skill sync", () => {
HOME: home,
},
paperclipSkillSync: {
desiredSkills: ["paperclip"],
desiredSkills: [paperclipKey],
},
},
} as const;
await syncPiSkills(configuredCtx, ["paperclip"]);
await syncPiSkills(configuredCtx, [paperclipKey]);
const clearedCtx = {
...configuredCtx,
@@ -81,8 +82,8 @@ describe("pi local skill sync", () => {
} as const;
const after = await syncPiSkills(clearedCtx, []);
expect(after.desiredSkills).toContain("paperclip");
expect(after.entries.find((entry) => entry.name === "paperclip")?.state).toBe("installed");
expect(after.desiredSkills).toContain(paperclipKey);
expect(after.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("installed");
expect((await fs.lstat(path.join(home, ".pi", "agent", "skills", "paperclip"))).isSymbolicLink()).toBe(true);
});
});

4
server/src/routes/agents.ts
View File

@@ -506,7 +506,7 @@ export function agentRoutes(db: Db) {
agent.adapterConfig as Record<string, unknown>,
);
const runtimeSkillEntries = await companySkills.listRuntimeSkillEntries(agent.companyId);
const requiredSkills = runtimeSkillEntries.filter((entry) => entry.required).map((entry) => entry.name);
const requiredSkills = runtimeSkillEntries.filter((entry) => entry.required).map((entry) => entry.key);
res.json(buildUnsupportedSkillSnapshot(agent.adapterType, Array.from(new Set([...requiredSkills, ...preference.desiredSkills]))));
return;
}
@@ -545,7 +545,7 @@ export function agentRoutes(db: Db) {
),
);
const runtimeSkillEntries = await companySkills.listRuntimeSkillEntries(agent.companyId);
const requiredSkills = runtimeSkillEntries.filter((entry) => entry.required).map((entry) => entry.name);
const requiredSkills = runtimeSkillEntries.filter((entry) => entry.required).map((entry) => entry.key);
const desiredSkills = Array.from(new Set([...requiredSkills, ...requestedSkills]));
const nextAdapterConfig = writePaperclipSkillSyncPreference(
agent.adapterConfig as Record<string, unknown>,

101
server/src/services/company-portability.ts
View File

@@ -51,6 +51,67 @@ const DEFAULT_COLLISION_STRATEGY: CompanyPortabilityCollisionStrategy = "rename"
const execFileAsync = promisify(execFile);
let bundledSkillsCommitPromise: Promise<string | null> | null = null;
function normalizeSkillSlug(value: string | null | undefined) {
return value ? normalizeAgentUrlKey(value) ?? null : null;
}
function normalizeSkillKey(value: string | null | undefined) {
if (!value) return null;
const segments = value
.split("/")
.map((segment) => normalizeSkillSlug(segment))
.filter((segment): segment is string => Boolean(segment));
return segments.length > 0 ? segments.join("/") : null;
}
function readSkillKey(frontmatter: Record<string, unknown>) {
const metadata = isPlainRecord(frontmatter.metadata) ? frontmatter.metadata : null;
const paperclip = isPlainRecord(metadata?.paperclip) ? metadata?.paperclip as Record<string, unknown> : null;
return normalizeSkillKey(
asString(frontmatter.key)
?? asString(frontmatter.skillKey)
?? asString(metadata?.skillKey)
?? asString(metadata?.canonicalKey)
?? asString(metadata?.paperclipSkillKey)
?? asString(paperclip?.skillKey)
?? asString(paperclip?.key),
);
}
function deriveManifestSkillKey(
frontmatter: Record<string, unknown>,
fallbackSlug: string,
metadata: Record<string, unknown> | null,
sourceType: string,
sourceLocator: string | null,
) {
const explicit = readSkillKey(frontmatter);
if (explicit) return explicit;
const slug = normalizeSkillSlug(asString(frontmatter.slug) ?? fallbackSlug) ?? "skill";
const sourceKind = asString(metadata?.sourceKind);
const owner = normalizeSkillSlug(asString(metadata?.owner));
const repo = normalizeSkillSlug(asString(metadata?.repo));
if ((sourceType === "github" || sourceKind === "github") && owner && repo) {
return `${owner}/${repo}/${slug}`;
}
if (sourceKind === "paperclip_bundled") {
return `paperclipai/paperclip/${slug}`;
}
if (sourceType === "url" || sourceKind === "url") {
try {
const host = normalizeSkillSlug(sourceLocator ? new URL(sourceLocator).host : null) ?? "url";
return `url/${host}/${slug}`;
} catch {
return `url/unknown/${slug}`;
}
}
return slug;
}
function skillPackageDir(key: string) {
return `skills/${key}`;
}
function isSensitiveEnvKey(key: string) {
const normalized = key.trim().toLowerCase();
return (
@@ -748,6 +809,8 @@ function shouldReferenceSkillOnExport(skill: CompanySkill, expandReferencedSkill
async function buildReferencedSkillMarkdown(skill: CompanySkill) {
const sourceEntry = await buildSkillSourceEntry(skill);
const frontmatter: Record<string, unknown> = {
key: skill.key,
slug: skill.slug,
name: skill.name,
description: skill.description ?? null,
};
@@ -761,7 +824,6 @@ async function buildReferencedSkillMarkdown(skill: CompanySkill) {
async function withSkillSourceMetadata(skill: CompanySkill, markdown: string) {
const sourceEntry = await buildSkillSourceEntry(skill);
if (!sourceEntry) return markdown;
const parsed = parseFrontmatterMarkdown(markdown);
const metadata = isPlainRecord(parsed.frontmatter.metadata)
? { ...parsed.frontmatter.metadata }
@@ -769,9 +831,20 @@ async function withSkillSourceMetadata(skill: CompanySkill, markdown: string) {
const existingSources = Array.isArray(metadata.sources)
? metadata.sources.filter((entry) => isPlainRecord(entry))
: [];
metadata.sources = [...existingSources, sourceEntry];
if (sourceEntry) {
metadata.sources = [...existingSources, sourceEntry];
}
metadata.skillKey = skill.key;
metadata.paperclipSkillKey = skill.key;
metadata.paperclip = {
...(isPlainRecord(metadata.paperclip) ? metadata.paperclip : {}),
skillKey: skill.key,
slug: skill.slug,
};
const frontmatter = {
...parsed.frontmatter,
key: skill.key,
slug: skill.slug,
metadata,
};
return buildMarkdown(frontmatter, parsed.body);
@@ -1043,7 +1116,7 @@ function readAgentSkillRefs(frontmatter: Record<string, unknown>) {
return Array.from(new Set(
skills
.filter((entry): entry is string => typeof entry === "string")
.map((entry) => normalizeAgentUrlKey(entry) ?? entry.trim())
.map((entry) => normalizeSkillKey(entry) ?? entry.trim())
.filter(Boolean),
));
}
@@ -1256,8 +1329,10 @@ function buildManifestFromPackageFiles(
sourceKind: "catalog",
};
}
const key = deriveManifestSkillKey(frontmatter, slug, normalizedMetadata, sourceType, sourceLocator);
manifest.skills.push({
key,
slug,
name: asString(frontmatter.name) ?? slug,
path: skillPath,
@@ -1688,15 +1763,16 @@ export function companyPortabilityService(db: Db) {
const paperclipTasksOut: Record<string, Record<string, unknown>> = {};
for (const skill of companySkillRows) {
const packageDir = skillPackageDir(skill.key);
if (shouldReferenceSkillOnExport(skill, Boolean(input.expandReferencedSkills))) {
files[`skills/${skill.slug}/SKILL.md`] = await buildReferencedSkillMarkdown(skill);
files[`${packageDir}/SKILL.md`] = await buildReferencedSkillMarkdown(skill);
continue;
}
for (const inventoryEntry of skill.fileInventory) {
const fileDetail = await companySkills.readFile(companyId, skill.id, inventoryEntry.path).catch(() => null);
if (!fileDetail) continue;
const filePath = `skills/${skill.slug}/${inventoryEntry.path}`;
const filePath = `${packageDir}/${inventoryEntry.path}`;
files[filePath] = inventoryEntry.path === "SKILL.md"
? await withSkillSourceMetadata(skill, fileDetail.content)
: fileDetail.content;
@@ -1908,7 +1984,13 @@ export function companyPortabilityService(db: Db) {
warnings.push("No agents selected for import.");
}
const availableSkillSlugs = new Set(source.manifest.skills.map((skill) => skill.slug));
const availableSkillKeys = new Set(source.manifest.skills.map((skill) => skill.key));
const availableSkillSlugs = new Map<string, CompanyPortabilitySkillManifestEntry[]>();
for (const skill of source.manifest.skills) {
const existing = availableSkillSlugs.get(skill.slug) ?? [];
existing.push(skill);
availableSkillSlugs.set(skill.slug, existing);
}
for (const agent of selectedAgents) {
const filePath = ensureMarkdownPath(agent.path);
@@ -1921,9 +2003,10 @@ export function companyPortabilityService(db: Db) {
if (parsed.frontmatter.kind && parsed.frontmatter.kind !== "agent") {
warnings.push(`Agent markdown ${filePath} does not declare kind: agent in frontmatter.`);
}
for (const skillSlug of agent.skills) {
if (!availableSkillSlugs.has(skillSlug)) {
warnings.push(`Agent ${agent.slug} references skill ${skillSlug}, but that skill is not present in the package.`);
for (const skillRef of agent.skills) {
const slugMatches = availableSkillSlugs.get(skillRef) ?? [];
if (!availableSkillKeys.has(skillRef) && slugMatches.length !== 1) {
warnings.push(`Agent ${agent.slug} references skill ${skillRef}, but that skill is not present in the package.`);
}
}
}

271
server/src/services/company-skills.ts
View File

@@ -1,3 +1,4 @@
import { createHash } from "node:crypto";
import { promises as fs } from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
@@ -31,6 +32,7 @@ import { secretService } from "./secrets.js";
type CompanySkillRow = typeof companySkills.$inferSelect;
type ImportedSkill = {
key: string;
slug: string;
name: string;
description: string | null;
@@ -52,6 +54,7 @@ type ParsedSkillImportSource = {
};
type SkillSourceMeta = {
skillKey?: string;
sourceKind?: string;
owner?: string;
repo?: string;
@@ -97,6 +100,86 @@ function normalizeSkillSlug(value: string | null | undefined) {
return value ? normalizeAgentUrlKey(value) ?? null : null;
}
function normalizeSkillKey(value: string | null | undefined) {
if (!value) return null;
const segments = value
.split("/")
.map((segment) => normalizeSkillSlug(segment))
.filter((segment): segment is string => Boolean(segment));
return segments.length > 0 ? segments.join("/") : null;
}
function hashSkillValue(value: string) {
return createHash("sha256").update(value).digest("hex").slice(0, 10);
}
function buildSkillRuntimeName(key: string, slug: string) {
if (key.startsWith("paperclipai/paperclip/")) return slug;
return `${slug}--${hashSkillValue(key)}`;
}
function readCanonicalSkillKey(frontmatter: Record<string, unknown>, metadata: Record<string, unknown> | null) {
const direct = normalizeSkillKey(
asString(frontmatter.key)
?? asString(frontmatter.skillKey)
?? asString(metadata?.skillKey)
?? asString(metadata?.canonicalKey)
?? asString(metadata?.paperclipSkillKey),
);
if (direct) return direct;
const paperclip = isPlainRecord(metadata?.paperclip) ? metadata?.paperclip as Record<string, unknown> : null;
return normalizeSkillKey(
asString(paperclip?.skillKey)
?? asString(paperclip?.key),
);
}
function deriveCanonicalSkillKey(
companyId: string,
input: Pick<ImportedSkill, "slug" | "sourceType" | "sourceLocator" | "metadata">,
) {
const slug = normalizeSkillSlug(input.slug) ?? "skill";
const metadata = isPlainRecord(input.metadata) ? input.metadata : null;
const explicitKey = readCanonicalSkillKey({}, metadata);
if (explicitKey) return explicitKey;
const sourceKind = asString(metadata?.sourceKind);
if (sourceKind === "paperclip_bundled") {
return `paperclipai/paperclip/${slug}`;
}
const owner = normalizeSkillSlug(asString(metadata?.owner));
const repo = normalizeSkillSlug(asString(metadata?.repo));
if ((input.sourceType === "github" || sourceKind === "github") && owner && repo) {
return `${owner}/${repo}/${slug}`;
}
if (input.sourceType === "url" || sourceKind === "url") {
const locator = asString(input.sourceLocator);
if (locator) {
try {
const url = new URL(locator);
const host = normalizeSkillSlug(url.host) ?? "url";
return `url/${host}/${hashSkillValue(locator)}/${slug}`;
} catch {
return `url/unknown/${hashSkillValue(locator)}/${slug}`;
}
}
}
if (input.sourceType === "local_path") {
if (sourceKind === "managed_local") {
return `company/${companyId}/${slug}`;
}
const locator = asString(input.sourceLocator);
if (locator) {
return `local/${hashSkillValue(path.resolve(locator))}/${slug}`;
}
}
return `company/${companyId}/${slug}`;
}
function classifyInventoryKind(relativePath: string): CompanySkillFileInventoryEntry["kind"] {
const normalized = normalizePortablePath(relativePath).toLowerCase();
if (normalized.endsWith("/skill.md") || normalized === "skill.md") return "skill";
@@ -417,7 +500,10 @@ function matchesRequestedSkill(relativeSkillPath: string, requestedSkillSlug: st
}
function deriveImportedSkillSlug(frontmatter: Record<string, unknown>, fallback: string) {
return normalizeSkillSlug(asString(frontmatter.name)) ?? normalizeAgentUrlKey(fallback) ?? "skill";
return normalizeSkillSlug(asString(frontmatter.slug))
?? normalizeSkillSlug(asString(frontmatter.name))
?? normalizeAgentUrlKey(fallback)
?? "skill";
}
function deriveImportedSkillSource(
@@ -425,6 +511,7 @@ function deriveImportedSkillSource(
fallbackSlug: string,
): Pick<ImportedSkill, "sourceType" | "sourceLocator" | "sourceRef" | "metadata"> {
const metadata = isPlainRecord(frontmatter.metadata) ? frontmatter.metadata : null;
const canonicalKey = readCanonicalSkillKey(frontmatter, metadata);
const rawSources = metadata && Array.isArray(metadata.sources) ? metadata.sources : [];
const sourceEntry = rawSources.find((entry) => isPlainRecord(entry)) as Record<string, unknown> | undefined;
const kind = asString(sourceEntry?.kind);
@@ -445,6 +532,7 @@ function deriveImportedSkillSource(
sourceLocator: url,
sourceRef: commit,
metadata: {
...(canonicalKey ? { skillKey: canonicalKey } : {}),
sourceKind: "github",
owner,
repo: repoName,
@@ -464,6 +552,7 @@ function deriveImportedSkillSource(
sourceLocator: url,
sourceRef: null,
metadata: {
...(canonicalKey ? { skillKey: canonicalKey } : {}),
sourceKind: "url",
},
};
@@ -475,12 +564,13 @@ function deriveImportedSkillSource(
sourceLocator: null,
sourceRef: null,
metadata: {
...(canonicalKey ? { skillKey: canonicalKey } : {}),
sourceKind: "catalog",
},
};
}
function readInlineSkillImports(files: Record<string, string>): ImportedSkill[] {
function readInlineSkillImports(companyId: string, files: Record<string, string>): ImportedSkill[] {
const normalizedFiles = normalizePackageFileMap(files);
const skillPaths = Object.keys(normalizedFiles).filter(
(entry) => path.posix.basename(entry).toLowerCase() === "skill.md",
@@ -507,6 +597,7 @@ function readInlineSkillImports(files: Record<string, string>): ImportedSkill[]
.sort((left, right) => left.path.localeCompare(right.path));
imports.push({
key: "",
slug,
name: asString(parsed.frontmatter.name) ?? slug,
description: asString(parsed.frontmatter.description),
@@ -520,6 +611,7 @@ function readInlineSkillImports(files: Record<string, string>): ImportedSkill[]
fileInventory: inventory,
metadata: source.metadata,
});
imports[imports.length - 1]!.key = deriveCanonicalSkillKey(companyId, imports[imports.length - 1]!);
}
return imports;
@@ -539,7 +631,7 @@ async function walkLocalFiles(root: string, current: string, out: string[]) {
}
}
async function readLocalSkillImports(sourcePath: string): Promise<ImportedSkill[]> {
async function readLocalSkillImports(companyId: string, sourcePath: string): Promise<ImportedSkill[]> {
const resolvedPath = path.resolve(sourcePath);
const stat = await fs.stat(resolvedPath).catch(() => null);
if (!stat) {
@@ -550,10 +642,24 @@ async function readLocalSkillImports(sourcePath: string): Promise<ImportedSkill[
const markdown = await fs.readFile(resolvedPath, "utf8");
const parsed = parseFrontmatterMarkdown(markdown);
const slug = deriveImportedSkillSlug(parsed.frontmatter, path.basename(path.dirname(resolvedPath)));
const skillKey = readCanonicalSkillKey(
parsed.frontmatter,
isPlainRecord(parsed.frontmatter.metadata) ? parsed.frontmatter.metadata : null,
);
const metadata = {
...(skillKey ? { skillKey } : {}),
sourceKind: "local_path",
};
const inventory: CompanySkillFileInventoryEntry[] = [
{ path: "SKILL.md", kind: "skill" },
];
return [{
key: deriveCanonicalSkillKey(companyId, {
slug,
sourceType: "local_path",
sourceLocator: path.dirname(resolvedPath),
metadata,
}),
slug,
name: asString(parsed.frontmatter.name) ?? slug,
description: asString(parsed.frontmatter.description),
@@ -565,7 +671,7 @@ async function readLocalSkillImports(sourcePath: string): Promise<ImportedSkill[
trustLevel: deriveTrustLevel(inventory),
compatibility: "compatible",
fileInventory: inventory,
metadata: { sourceKind: "local_path" },
metadata,
}];
}
@@ -583,6 +689,14 @@ async function readLocalSkillImports(sourcePath: string): Promise<ImportedSkill[
const markdown = await fs.readFile(path.join(root, skillPath), "utf8");
const parsed = parseFrontmatterMarkdown(markdown);
const slug = deriveImportedSkillSlug(parsed.frontmatter, path.posix.basename(skillDir));
const skillKey = readCanonicalSkillKey(
parsed.frontmatter,
isPlainRecord(parsed.frontmatter.metadata) ? parsed.frontmatter.metadata : null,
);
const metadata = {
...(skillKey ? { skillKey } : {}),
sourceKind: "local_path",
};
const inventory = allFiles
.filter((entry) => entry === skillPath || entry.startsWith(`${skillDir}/`))
.map((entry) => {
@@ -594,6 +708,12 @@ async function readLocalSkillImports(sourcePath: string): Promise<ImportedSkill[
})
.sort((left, right) => left.path.localeCompare(right.path));
imports.push({
key: deriveCanonicalSkillKey(companyId, {
slug,
sourceType: "local_path",
sourceLocator: path.join(root, skillDir),
metadata,
}),
slug,
name: asString(parsed.frontmatter.name) ?? slug,
description: asString(parsed.frontmatter.description),
@@ -605,7 +725,7 @@ async function readLocalSkillImports(sourcePath: string): Promise<ImportedSkill[
trustLevel: deriveTrustLevel(inventory),
compatibility: "compatible",
fileInventory: inventory,
metadata: { sourceKind: "local_path" },
metadata,
});
}
@@ -613,6 +733,7 @@ async function readLocalSkillImports(sourcePath: string): Promise<ImportedSkill[
}
async function readUrlSkillImports(
companyId: string,
sourceUrl: string,
requestedSkillSlug: string | null = null,
): Promise<{ skills: ImportedSkill[]; warnings: string[] }> {
@@ -654,9 +775,22 @@ async function readUrlSkillImports(
const parsedMarkdown = parseFrontmatterMarkdown(markdown);
const skillDir = path.posix.dirname(relativeSkillPath);
const slug = deriveImportedSkillSlug(parsedMarkdown.frontmatter, path.posix.basename(skillDir));
const skillKey = readCanonicalSkillKey(
parsedMarkdown.frontmatter,
isPlainRecord(parsedMarkdown.frontmatter.metadata) ? parsedMarkdown.frontmatter.metadata : null,
);
if (requestedSkillSlug && !matchesRequestedSkill(relativeSkillPath, requestedSkillSlug) && slug !== requestedSkillSlug) {
continue;
}
const metadata = {
...(skillKey ? { skillKey } : {}),
sourceKind: "github",
owner: parsed.owner,
repo: parsed.repo,
ref: ref,
trackingRef,
repoSkillDir: basePrefix ? `${basePrefix}${skillDir}` : skillDir,
};
const inventory = filteredPaths
.filter((entry) => entry === relativeSkillPath || entry.startsWith(`${skillDir}/`))
.map((entry) => ({
@@ -665,6 +799,12 @@ async function readUrlSkillImports(
}))
.sort((left, right) => left.path.localeCompare(right.path));
skills.push({
key: deriveCanonicalSkillKey(companyId, {
slug,
sourceType: "github",
sourceLocator: sourceUrl,
metadata,
}),
slug,
name: asString(parsedMarkdown.frontmatter.name) ?? slug,
description: asString(parsedMarkdown.frontmatter.description),
@@ -675,14 +815,7 @@ async function readUrlSkillImports(
trustLevel: deriveTrustLevel(inventory),
compatibility: "compatible",
fileInventory: inventory,
metadata: {
sourceKind: "github",
owner: parsed.owner,
repo: parsed.repo,
ref: ref,
trackingRef,
repoSkillDir: basePrefix ? `${basePrefix}${skillDir}` : skillDir,
},
metadata,
});
}
if (skills.length === 0) {
@@ -701,9 +834,23 @@ async function readUrlSkillImports(
const urlObj = new URL(url);
const fileName = path.posix.basename(urlObj.pathname);
const slug = deriveImportedSkillSlug(parsedMarkdown.frontmatter, fileName.replace(/\.md$/i, ""));
const skillKey = readCanonicalSkillKey(
parsedMarkdown.frontmatter,
isPlainRecord(parsedMarkdown.frontmatter.metadata) ? parsedMarkdown.frontmatter.metadata : null,
);
const metadata = {
...(skillKey ? { skillKey } : {}),
sourceKind: "url",
};
const inventory: CompanySkillFileInventoryEntry[] = [{ path: "SKILL.md", kind: "skill" }];
return {
skills: [{
key: deriveCanonicalSkillKey(companyId, {
slug,
sourceType: "url",
sourceLocator: url,
metadata,
}),
slug,
name: asString(parsedMarkdown.frontmatter.name) ?? slug,
description: asString(parsedMarkdown.frontmatter.description),
@@ -714,9 +861,7 @@ async function readUrlSkillImports(
trustLevel: deriveTrustLevel(inventory),
compatibility: "compatible",
fileInventory: inventory,
metadata: {
sourceKind: "url",
},
metadata,
}],
warnings,
};
@@ -760,6 +905,34 @@ function getSkillMeta(skill: CompanySkill): SkillSourceMeta {
return isPlainRecord(skill.metadata) ? skill.metadata as SkillSourceMeta : {};
}
function resolveSkillReference(
skills: CompanySkill[],
reference: string,
): CompanySkill | null {
const normalizedReference = normalizeSkillKey(reference) ?? normalizeSkillSlug(reference);
if (!normalizedReference) return null;
const byKey = skills.find((skill) => skill.key === normalizedReference);
if (byKey) return byKey;
const bySlug = skills.filter((skill) => skill.slug === normalizedReference);
if (bySlug.length === 1) return bySlug[0] ?? null;
return null;
}
function resolveDesiredSkillKeys(
skills: CompanySkill[],
config: Record<string, unknown>,
) {
const preference = readPaperclipSkillSyncPreference(config);
return Array.from(new Set(
preference.desiredSkills
.map((reference) => resolveSkillReference(skills, reference)?.key ?? normalizeSkillKey(reference))
.filter((value): value is string => Boolean(value)),
));
}
function normalizeSkillDirectory(skill: CompanySkill) {
if ((skill.sourceType !== "local_path" && skill.sourceType !== "catalog") || !skill.sourceLocator) return null;
const resolved = path.resolve(skill.sourceLocator);
@@ -886,6 +1059,7 @@ function toCompanySkillListItem(skill: CompanySkill, attachedAgentCount: number)
return {
id: skill.id,
companyId: skill.companyId,
key: skill.key,
slug: skill.slug,
name: skill.name,
description: skill.description,
@@ -913,9 +1087,16 @@ export function companySkillService(db: Db) {
for (const skillsRoot of resolveBundledSkillsRoot()) {
const stats = await fs.stat(skillsRoot).catch(() => null);
if (!stats?.isDirectory()) continue;
const bundledSkills = await readLocalSkillImports(skillsRoot)
const bundledSkills = await readLocalSkillImports(companyId, skillsRoot)
.then((skills) => skills.map((skill) => ({
...skill,
key: deriveCanonicalSkillKey(companyId, {
...skill,
metadata: {
...(skill.metadata ?? {}),
sourceKind: "paperclip_bundled",
},
}),
metadata: {
...(skill.metadata ?? {}),
sourceKind: "paperclip_bundled",
@@ -933,8 +1114,8 @@ export function companySkillService(db: Db) {
const agentRows = await agents.list(companyId);
return rows.map((skill) => {
const attachedAgentCount = agentRows.filter((agent) => {
const preference = readPaperclipSkillSyncPreference(agent.adapterConfig as Record<string, unknown>);
return preference.desiredSkills.includes(skill.slug);
const desiredSkills = resolveDesiredSkillKeys(rows, agent.adapterConfig as Record<string, unknown>);
return desiredSkills.includes(skill.key);
}).length;
return toCompanySkillListItem(skill, attachedAgentCount);
});
@@ -946,7 +1127,7 @@ export function companySkillService(db: Db) {
.select()
.from(companySkills)
.where(eq(companySkills.companyId, companyId))
.orderBy(asc(companySkills.name), asc(companySkills.slug));
.orderBy(asc(companySkills.name), asc(companySkills.key));
return rows.map((row) => toCompanySkill(row));
}
@@ -959,20 +1140,21 @@ export function companySkillService(db: Db) {
return row ? toCompanySkill(row) : null;
}
async function getBySlug(companyId: string, slug: string) {
async function getByKey(companyId: string, key: string) {
const row = await db
.select()
.from(companySkills)
.where(and(eq(companySkills.companyId, companyId), eq(companySkills.slug, slug)))
.where(and(eq(companySkills.companyId, companyId), eq(companySkills.key, key)))
.then((rows) => rows[0] ?? null);
return row ? toCompanySkill(row) : null;
}
async function usage(companyId: string, slug: string): Promise<CompanySkillUsageAgent[]> {
async function usage(companyId: string, key: string): Promise<CompanySkillUsageAgent[]> {
const skills = await listFull(companyId);
const agentRows = await agents.list(companyId);
const desiredAgents = agentRows.filter((agent) => {
const preference = readPaperclipSkillSyncPreference(agent.adapterConfig as Record<string, unknown>);
return preference.desiredSkills.includes(slug);
const desiredSkills = resolveDesiredSkillKeys(skills, agent.adapterConfig as Record<string, unknown>);
return desiredSkills.includes(key);
});
return Promise.all(
@@ -998,7 +1180,7 @@ export function companySkillService(db: Db) {
paperclipRuntimeSkills: runtimeSkillEntries,
},
});
actualState = snapshot.entries.find((entry) => entry.name === slug)?.state
actualState = snapshot.entries.find((entry) => entry.key === key)?.state
?? (snapshot.supported ? "missing" : "unsupported");
} catch {
actualState = "unknown";
@@ -1021,7 +1203,7 @@ export function companySkillService(db: Db) {
await ensureBundledSkills(companyId);
const skill = await getById(id);
if (!skill || skill.companyId !== companyId) return null;
const usedByAgents = await usage(companyId, skill.slug);
const usedByAgents = await usage(companyId, skill.key);
return enrichSkill(skill, usedByAgents.length, usedByAgents);
}
@@ -1147,6 +1329,7 @@ export function companySkillService(db: Db) {
const parsed = parseFrontmatterMarkdown(markdown);
const imported = await upsertImportedSkills(companyId, [{
key: `company/${companyId}/${slug}`,
slug,
name: asString(parsed.frontmatter.name) ?? input.name,
description: asString(parsed.frontmatter.description) ?? input.description?.trim() ?? null,
@@ -1216,10 +1399,10 @@ export function companySkillService(db: Db) {
throw unprocessable("Skill source locator is missing.");
}
const result = await readUrlSkillImports(skill.sourceLocator, skill.slug);
const matching = result.skills.find((entry) => entry.slug === skill.slug) ?? result.skills[0] ?? null;
const result = await readUrlSkillImports(companyId, skill.sourceLocator, skill.slug);
const matching = result.skills.find((entry) => entry.key === skill.key) ?? result.skills[0] ?? null;
if (!matching) {
throw unprocessable(`Skill ${skill.slug} could not be re-imported from its source.`);
throw unprocessable(`Skill ${skill.key} could not be re-imported from its source.`);
}
const imported = await upsertImportedSkills(companyId, [matching]);
@@ -1234,7 +1417,7 @@ export function companySkillService(db: Db) {
const packageDir = skill.packageDir ? normalizePortablePath(skill.packageDir) : null;
if (!packageDir) return null;
const catalogRoot = path.resolve(resolveManagedSkillsRoot(companyId), "__catalog__");
const skillDir = path.resolve(catalogRoot, skill.slug);
const skillDir = path.resolve(catalogRoot, buildSkillRuntimeName(skill.key, skill.slug));
await fs.rm(skillDir, { recursive: true, force: true });
await fs.mkdir(skillDir, { recursive: true });
@@ -1254,7 +1437,7 @@ export function companySkillService(db: Db) {
async function materializeRuntimeSkillFiles(companyId: string, skill: CompanySkill) {
const runtimeRoot = path.resolve(resolveManagedSkillsRoot(companyId), "__runtime__");
const skillDir = path.resolve(runtimeRoot, skill.slug);
const skillDir = path.resolve(runtimeRoot, buildSkillRuntimeName(skill.key, skill.slug));
await fs.rm(skillDir, { recursive: true, force: true });
await fs.mkdir(skillDir, { recursive: true });
@@ -1275,7 +1458,7 @@ export function companySkillService(db: Db) {
.select()
.from(companySkills)
.where(eq(companySkills.companyId, companyId))
.orderBy(asc(companySkills.name), asc(companySkills.slug));
.orderBy(asc(companySkills.name), asc(companySkills.key));
const out: PaperclipSkillEntry[] = [];
for (const row of rows) {
@@ -1289,7 +1472,8 @@ export function companySkillService(db: Db) {
const required = sourceKind === "paperclip_bundled";
out.push({
name: skill.slug,
key: skill.key,
runtimeName: buildSkillRuntimeName(skill.key, skill.slug),
source,
required,
requiredReason: required
@@ -1298,14 +1482,14 @@ export function companySkillService(db: Db) {
});
}
out.sort((left, right) => left.name.localeCompare(right.name));
out.sort((left, right) => left.key.localeCompare(right.key));
return out;
}
async function importPackageFiles(companyId: string, files: Record<string, string>): Promise<CompanySkill[]> {
await ensureBundledSkills(companyId);
const normalizedFiles = normalizePackageFileMap(files);
const importedSkills = readInlineSkillImports(normalizedFiles);
const importedSkills = readInlineSkillImports(companyId, normalizedFiles);
if (importedSkills.length === 0) return [];
for (const skill of importedSkills) {
@@ -1322,7 +1506,7 @@ export function companySkillService(db: Db) {
async function upsertImportedSkills(companyId: string, imported: ImportedSkill[]): Promise<CompanySkill[]> {
const out: CompanySkill[] = [];
for (const skill of imported) {
const existing = await getBySlug(companyId, skill.slug);
const existing = await getByKey(companyId, skill.key);
const existingMeta = existing ? getSkillMeta(existing) : {};
const incomingMeta = skill.metadata && isPlainRecord(skill.metadata) ? skill.metadata : {};
const incomingOwner = asString(incomingMeta.owner);
@@ -1339,8 +1523,13 @@ export function companySkillService(db: Db) {
continue;
}
const metadata = {
...(skill.metadata ?? {}),
skillKey: skill.key,
};
const values = {
companyId,
key: skill.key,
slug: skill.slug,
name: skill.name,
description: skill.description,
@@ -1351,7 +1540,7 @@ export function companySkillService(db: Db) {
trustLevel: skill.trustLevel,
compatibility: skill.compatibility,
fileInventory: serializeFileInventory(skill.fileInventory),
metadata: skill.metadata,
metadata,
updatedAt: new Date(),
};
const row = existing
@@ -1378,11 +1567,11 @@ export function companySkillService(db: Db) {
const local = !/^https?:\/\//i.test(parsed.resolvedSource);
const { skills, warnings } = local
? {
skills: (await readLocalSkillImports(parsed.resolvedSource))
skills: (await readLocalSkillImports(companyId, parsed.resolvedSource))
.filter((skill) => !parsed.requestedSkillSlug || skill.slug === parsed.requestedSkillSlug),
warnings: parsed.warnings,
}
: await readUrlSkillImports(parsed.resolvedSource, parsed.requestedSkillSlug)
: await readUrlSkillImports(companyId, parsed.resolvedSource, parsed.requestedSkillSlug)
.then((result) => ({
skills: result.skills,
warnings: [...parsed.warnings, ...result.warnings],
@@ -1405,7 +1594,7 @@ export function companySkillService(db: Db) {
list,
listFull,
getById,
getBySlug,
getByKey,
detail,
updateStatus,
readFile,

47
ui/src/pages/AgentDetail.tsx
View File

@@ -1233,7 +1233,7 @@ function AgentSkillsTab({
}) {
type SkillRow = {
id: string;
slug: string;
key: string;
name: string;
description: string | null;
detail: string | null;
@@ -1316,50 +1316,50 @@ function AgentSkillsTab({
return () => window.clearTimeout(timeout);
}, [skillDraft, skillSnapshot, syncSkills.isPending, syncSkills.mutate]);
const companySkillBySlug = useMemo(
() => new Map((companySkills ?? []).map((skill) => [skill.slug, skill])),
const companySkillByKey = useMemo(
() => new Map((companySkills ?? []).map((skill) => [skill.key, skill])),
[companySkills],
);
const adapterEntryByName = useMemo(
() => new Map((skillSnapshot?.entries ?? []).map((entry) => [entry.name, entry])),
const adapterEntryByKey = useMemo(
() => new Map((skillSnapshot?.entries ?? []).map((entry) => [entry.key, entry])),
[skillSnapshot],
);
const optionalSkillRows = useMemo<SkillRow[]>(
() =>
(companySkills ?? [])
.filter((skill) => !adapterEntryByName.get(skill.slug)?.required)
.filter((skill) => !adapterEntryByKey.get(skill.key)?.required)
.map((skill) => ({
id: skill.id,
slug: skill.slug,
key: skill.key,
name: skill.name,
description: skill.description,
detail: adapterEntryByName.get(skill.slug)?.detail ?? null,
detail: adapterEntryByKey.get(skill.key)?.detail ?? null,
linkTo: `/skills/${skill.id}`,
adapterEntry: adapterEntryByName.get(skill.slug) ?? null,
adapterEntry: adapterEntryByKey.get(skill.key) ?? null,
})),
[adapterEntryByName, companySkills],
[adapterEntryByKey, companySkills],
);
const requiredSkillRows = useMemo<SkillRow[]>(
() =>
(skillSnapshot?.entries ?? [])
.filter((entry) => entry.required)
.map((entry) => {
const companySkill = companySkillBySlug.get(entry.name);
const companySkill = companySkillByKey.get(entry.key);
return {
id: companySkill?.id ?? `required:${entry.name}`,
slug: entry.name,
name: companySkill?.name ?? entry.name,
id: companySkill?.id ?? `required:${entry.key}`,
key: entry.key,
name: companySkill?.name ?? entry.key,
description: companySkill?.description ?? null,
detail: entry.detail ?? null,
linkTo: companySkill ? `/skills/${companySkill.id}` : null,
adapterEntry: entry,
};
}),
[companySkillBySlug, skillSnapshot],
[companySkillByKey, skillSnapshot],
);
const desiredOnlyMissingSkills = useMemo(
() => skillDraft.filter((slug) => !companySkillBySlug.has(slug)),
[companySkillBySlug, skillDraft],
() => skillDraft.filter((key) => !companySkillByKey.has(key)),
[companySkillByKey, skillDraft],
);
const skillApplicationLabel = useMemo(() => {
switch (skillSnapshot?.mode) {
@@ -1424,9 +1424,9 @@ function AgentSkillsTab({
<>
{(() => {
const renderSkillRow = (skill: SkillRow) => {
const adapterEntry = skill.adapterEntry ?? adapterEntryByName.get(skill.slug);
const adapterEntry = skill.adapterEntry ?? adapterEntryByKey.get(skill.key);
const required = Boolean(adapterEntry?.required);
const checked = required || skillDraft.includes(skill.slug);
const checked = required || skillDraft.includes(skill.key);
const disabled = required || skillSnapshot?.mode === "unsupported";
const checkbox = (
<input
@@ -1435,8 +1435,8 @@ function AgentSkillsTab({
disabled={disabled}
onChange={(event) => {
const next = event.target.checked
? Array.from(new Set([...skillDraft, skill.slug]))
: skillDraft.filter((value) => value !== skill.slug);
? Array.from(new Set([...skillDraft, skill.key]))
: skillDraft.filter((value) => value !== skill.key);
setSkillDraft(next);
}}
className="mt-0.5 disabled:cursor-not-allowed disabled:opacity-60"
@@ -1468,7 +1468,10 @@ function AgentSkillsTab({
)}
<div className="min-w-0 flex-1">
<div className="flex items-center justify-between gap-3">
<span className="truncate font-medium">{skill.name}</span>
<div className="min-w-0">
<span className="truncate font-medium">{skill.name}</span>
<div className="truncate font-mono text-[11px] text-muted-foreground">{skill.key}</div>
</div>
{skill.linkTo ? (
<Link
to={skill.linkTo}

16
ui/src/pages/CompanyExport.tsx
View File

@@ -540,17 +540,23 @@ export function CompanyExport() {
}
}
function handleSkillClick(skillSlug: string) {
function handleSkillClick(skillKey: string) {
if (!exportData) return;
// Find the SKILL.md file for this skill slug
const skillPath = `skills/${skillSlug}/SKILL.md`;
const manifestSkill = exportData.manifest.skills.find(
(skill) => skill.key === skillKey || skill.slug === skillKey,
);
const skillPath = manifestSkill?.path ?? `skills/${skillKey}/SKILL.md`;
if (!(skillPath in exportData.files)) return;
// Select the file and expand parent dirs
setSelectedFile(skillPath);
setExpandedDirs((prev) => {
const next = new Set(prev);
next.add("skills");
next.add(`skills/${skillSlug}`);
const parts = skillPath.split("/").slice(0, -1);
let current = "";
for (const part of parts) {
current = current ? `${current}/${part}` : part;
next.add(current);
}
return next;
});
}

9
ui/src/pages/CompanySkills.tsx
View File

@@ -389,7 +389,7 @@ function SkillList({
onSelectPath: (skillId: string, path: string) => void;
}) {
const filteredSkills = skills.filter((skill) => {
const haystack = `${skill.name} ${skill.slug} ${skill.sourceLabel ?? ""}`.toLowerCase();
const haystack = `${skill.name} ${skill.key} ${skill.slug} ${skill.sourceLabel ?? ""}`.toLowerCase();
return haystack.includes(skillFilter.toLowerCase());
});
@@ -435,6 +435,9 @@ function SkillList({
<span className="block min-w-0 overflow-hidden text-[13px] font-medium leading-5 [display:-webkit-box] [-webkit-box-orient:vertical] [-webkit-line-clamp:3]">
{skill.name}
</span>
<span className="truncate font-mono text-[11px] text-muted-foreground">
{skill.key}
</span>
</span>
</Link>
<button
@@ -596,6 +599,10 @@ function SkillPane({
)}
</div>
)}
<div className="flex items-center gap-2">
<span className="text-[11px] uppercase tracking-[0.18em] text-muted-foreground">Key</span>
<span className="font-mono text-xs">{detail.key}</span>
</div>
<div className="flex items-center gap-2">
<span className="text-[11px] uppercase tracking-[0.18em] text-muted-foreground">Mode</span>
<span>{detail.editable ? "Editable" : "Read only"}</span>