ake/paperclip
1
0
Fork 0
mirror of https://github.com/alkimake/paperclip.git synced 2026-06-18 19:50:38 +09:00
Code Issues Projects Releases Packages Wiki Activity

Add unmanaged skill provenance to agent skills

Browse source 
Expose adapter-discovered user-installed skills with provenance metadata, share persistent skill snapshot classification across local adapters, and render unmanaged skills as a read-only section in the agent skills UI.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
dotta 2026-03-18 14:21:50 -05:00
parent 58d7f59477
commit cfc53bf96b
19 changed files with 497 additions and 501 deletions
Download patch file Download diff file Expand all files Collapse all files

42
packages/adapters/claude-local/src/server/skills.ts
View file

@ -1,3 +1,4 @@
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
import type {
@ -7,22 +8,42 @@ import type {
} from "@paperclipai/adapter-utils";
import {
readPaperclipRuntimeSkillEntries,
readInstalledSkillTargets,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
function asString(value: unknown): string | null {
return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
}
function resolveClaudeSkillsHome(config: Record<string, unknown>) {
const env =
typeof config.env === "object" && config.env !== null && !Array.isArray(config.env)
? (config.env as Record<string, unknown>)
: {};
const configuredHome = asString(env.HOME);
const home = configuredHome ? path.resolve(configuredHome) : os.homedir();
return path.join(home, ".claude", "skills");
}
async function buildClaudeSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveClaudeSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
key: entry.key,
runtimeName: entry.runtimeName,
desired: desiredSet.has(entry.key),
managed: true,
state: desiredSet.has(entry.key) ? "configured" : "available",
origin: entry.required ? "paperclip_required" : "company_managed",
originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
readOnly: false,
sourcePath: entry.source,
targetPath: null,
detail: desiredSet.has(entry.key)
@ -42,12 +63,33 @@ async function buildClaudeSkillSnapshot(config: Record<string, unknown>): Promis
desired: true,
managed: true,
state: "missing",
origin: "external_unknown",
originLabel: "External or unavailable",
readOnly: false,
sourcePath: undefined,
targetPath: undefined,
detail: "Paperclip cannot find this skill in the local runtime skills directory.",
});
}
for (const [name, installedEntry] of installed.entries()) {
if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
entries.push({
key: name,
runtimeName: name,
desired: false,
managed: false,
state: "external",
origin: "user_installed",
originLabel: "User-installed",
locationLabel: "~/.claude/skills",
readOnly: true,
sourcePath: null,
targetPath: installedEntry.targetPath ?? path.join(skillsHome, name),
detail: "Installed outside Paperclip management in the Claude skills home.",
});
}
entries.sort((left, right) => left.key.localeCompare(right.key));
return {

110
packages/adapters/codex-local/src/server/skills.ts
View file

@ -3,12 +3,13 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import type {
AdapterSkillContext,
AdapterSkillEntry,
AdapterSkillSnapshot,
} from "@paperclipai/adapter-utils";
import {
buildPersistentSkillSnapshot,
ensurePaperclipSkillSymlink,
readPaperclipRuntimeSkillEntries,
readInstalledSkillTargets,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
import { resolveCodexHomeDir } from "./codex-home.js";
@ -29,111 +30,22 @@ function resolveCodexSkillsHome(config: Record<string, unknown>) {
return path.join(home, "skills");
}
async function readInstalledSkillTargets(skillsHome: string) {
const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
const out = new Map<string, { targetPath: string | null; kind: "symlink" | "directory" | "file" }>();
for (const entry of entries) {
const fullPath = path.join(skillsHome, entry.name);
if (entry.isSymbolicLink()) {
const linkedPath = await fs.readlink(fullPath).catch(() => null);
out.set(entry.name, {
targetPath: linkedPath ? path.resolve(path.dirname(fullPath), linkedPath) : null,
kind: "symlink",
});
continue;
}
if (entry.isDirectory()) {
out.set(entry.name, { targetPath: fullPath, kind: "directory" });
continue;
}
out.set(entry.name, { targetPath: fullPath, kind: "file" });
}
return out;
}
async function buildCodexSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveCodexSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
const entries: AdapterSkillEntry[] = [];
const warnings: string[] = [];
for (const available of availableEntries) {
const installedEntry = installed.get(available.runtimeName) ?? null;
const desired = desiredSet.has(available.key);
let state: AdapterSkillEntry["state"] = "available";
let managed = false;
let detail: string | null = null;
if (installedEntry?.targetPath === available.source) {
managed = true;
state = desired ? "installed" : "stale";
} else if (installedEntry) {
state = "external";
detail = desired
? "Skill name is occupied by an external installation."
: "Installed outside Paperclip management.";
} else if (desired) {
state = "missing";
detail = "Configured but not currently linked into the Codex skills home.";
}
entries.push({
key: available.key,
runtimeName: available.runtimeName,
desired,
managed,
state,
sourcePath: available.source,
targetPath: path.join(skillsHome, available.runtimeName),
detail,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
});
}
for (const desiredSkill of desiredSkills) {
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
sourcePath: null,
targetPath: null,
detail: "Paperclip cannot find this skill in the local runtime skills directory.",
});
}
for (const [name, installedEntry] of installed.entries()) {
if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
entries.push({
key: name,
runtimeName: name,
desired: false,
managed: false,
state: "external",
sourcePath: null,
targetPath: installedEntry.targetPath ?? path.join(skillsHome, name),
detail: "Installed outside Paperclip management.",
});
}
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
return buildPersistentSkillSnapshot({
adapterType: "codex_local",
supported: true,
mode: "persistent",
availableEntries,
desiredSkills,
entries,
warnings,
};
installed,
skillsHome,
locationLabel: "$CODEX_HOME/skills",
missingDetail: "Configured but not currently linked into the Codex skills home.",
externalConflictDetail: "Skill name is occupied by an external installation.",
externalDetail: "Installed outside Paperclip management.",
});
}
export async function listCodexSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

110
packages/adapters/cursor-local/src/server/skills.ts
View file

@ -4,12 +4,13 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import type {
AdapterSkillContext,
AdapterSkillEntry,
AdapterSkillSnapshot,
} from "@paperclipai/adapter-utils";
import {
buildPersistentSkillSnapshot,
ensurePaperclipSkillSymlink,
readPaperclipRuntimeSkillEntries,
readInstalledSkillTargets,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
@ -29,111 +30,22 @@ function resolveCursorSkillsHome(config: Record<string, unknown>) {
return path.join(home, ".cursor", "skills");
}
async function readInstalledSkillTargets(skillsHome: string) {
const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
const out = new Map<string, { targetPath: string | null; kind: "symlink" | "directory" | "file" }>();
for (const entry of entries) {
const fullPath = path.join(skillsHome, entry.name);
if (entry.isSymbolicLink()) {
const linkedPath = await fs.readlink(fullPath).catch(() => null);
out.set(entry.name, {
targetPath: linkedPath ? path.resolve(path.dirname(fullPath), linkedPath) : null,
kind: "symlink",
});
continue;
}
if (entry.isDirectory()) {
out.set(entry.name, { targetPath: fullPath, kind: "directory" });
continue;
}
out.set(entry.name, { targetPath: fullPath, kind: "file" });
}
return out;
}
async function buildCursorSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveCursorSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
const entries: AdapterSkillEntry[] = [];
const warnings: string[] = [];
for (const available of availableEntries) {
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;
if (installedEntry?.targetPath === available.source) {
managed = true;
state = desired ? "installed" : "stale";
} else if (installedEntry) {
state = "external";
detail = desired
? "Skill name is occupied by an external installation."
: "Installed outside Paperclip management.";
} else if (desired) {
state = "missing";
detail = "Configured but not currently linked into the Cursor skills home.";
}
entries.push({
key: available.key,
runtimeName: available.runtimeName,
desired,
managed,
state,
sourcePath: available.source,
targetPath: path.join(skillsHome, available.runtimeName),
detail,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
});
}
for (const desiredSkill of desiredSkills) {
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
sourcePath: null,
targetPath: null,
detail: "Paperclip cannot find this skill in the local runtime skills directory.",
});
}
for (const [name, installedEntry] of installed.entries()) {
if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
entries.push({
key: name,
runtimeName: name,
desired: false,
managed: false,
state: "external",
sourcePath: null,
targetPath: installedEntry.targetPath ?? path.join(skillsHome, name),
detail: "Installed outside Paperclip management.",
});
}
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
return buildPersistentSkillSnapshot({
adapterType: "cursor",
supported: true,
mode: "persistent",
availableEntries,
desiredSkills,
entries,
warnings,
};
installed,
skillsHome,
locationLabel: "~/.cursor/skills",
missingDetail: "Configured but not currently linked into the Cursor skills home.",
externalConflictDetail: "Skill name is occupied by an external installation.",
externalDetail: "Installed outside Paperclip management.",
});
}
export async function listCursorSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

110
packages/adapters/gemini-local/src/server/skills.ts
View file

@ -4,12 +4,13 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import type {
AdapterSkillContext,
AdapterSkillEntry,
AdapterSkillSnapshot,
} from "@paperclipai/adapter-utils";
import {
buildPersistentSkillSnapshot,
ensurePaperclipSkillSymlink,
readPaperclipRuntimeSkillEntries,
readInstalledSkillTargets,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
@ -29,111 +30,22 @@ function resolveGeminiSkillsHome(config: Record<string, unknown>) {
return path.join(home, ".gemini", "skills");
}
async function readInstalledSkillTargets(skillsHome: string) {
const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
const out = new Map<string, { targetPath: string | null; kind: "symlink" | "directory" | "file" }>();
for (const entry of entries) {
const fullPath = path.join(skillsHome, entry.name);
if (entry.isSymbolicLink()) {
const linkedPath = await fs.readlink(fullPath).catch(() => null);
out.set(entry.name, {
targetPath: linkedPath ? path.resolve(path.dirname(fullPath), linkedPath) : null,
kind: "symlink",
});
continue;
}
if (entry.isDirectory()) {
out.set(entry.name, { targetPath: fullPath, kind: "directory" });
continue;
}
out.set(entry.name, { targetPath: fullPath, kind: "file" });
}
return out;
}
async function buildGeminiSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveGeminiSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
const entries: AdapterSkillEntry[] = [];
const warnings: string[] = [];
for (const available of availableEntries) {
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;
if (installedEntry?.targetPath === available.source) {
managed = true;
state = desired ? "installed" : "stale";
} else if (installedEntry) {
state = "external";
detail = desired
? "Skill name is occupied by an external installation."
: "Installed outside Paperclip management.";
} else if (desired) {
state = "missing";
detail = "Configured but not currently linked into the Gemini skills home.";
}
entries.push({
key: available.key,
runtimeName: available.runtimeName,
desired,
managed,
state,
sourcePath: available.source,
targetPath: path.join(skillsHome, available.runtimeName),
detail,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
});
}
for (const desiredSkill of desiredSkills) {
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
sourcePath: null,
targetPath: null,
detail: "Paperclip cannot find this skill in the local runtime skills directory.",
});
}
for (const [name, installedEntry] of installed.entries()) {
if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
entries.push({
key: name,
runtimeName: name,
desired: false,
managed: false,
state: "external",
sourcePath: null,
targetPath: installedEntry.targetPath ?? path.join(skillsHome, name),
detail: "Installed outside Paperclip management.",
});
}
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
return buildPersistentSkillSnapshot({
adapterType: "gemini_local",
supported: true,
mode: "persistent",
availableEntries,
desiredSkills,
entries,
warnings,
};
installed,
skillsHome,
locationLabel: "~/.gemini/skills",
missingDetail: "Configured but not currently linked into the Gemini skills home.",
externalConflictDetail: "Skill name is occupied by an external installation.",
externalDetail: "Installed outside Paperclip management.",
});
}
export async function listGeminiSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

117
packages/adapters/opencode-local/src/server/skills.ts
View file

@ -4,12 +4,13 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import type {
AdapterSkillContext,
AdapterSkillEntry,
AdapterSkillSnapshot,
} from "@paperclipai/adapter-utils";
import {
buildPersistentSkillSnapshot,
ensurePaperclipSkillSymlink,
readPaperclipRuntimeSkillEntries,
readInstalledSkillTargets,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
@ -29,114 +30,26 @@ function resolveOpenCodeSkillsHome(config: Record<string, unknown>) {
return path.join(home, ".claude", "skills");
}
async function readInstalledSkillTargets(skillsHome: string) {
const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
const out = new Map<string, { targetPath: string | null; kind: "symlink" | "directory" | "file" }>();
for (const entry of entries) {
const fullPath = path.join(skillsHome, entry.name);
if (entry.isSymbolicLink()) {
const linkedPath = await fs.readlink(fullPath).catch(() => null);
out.set(entry.name, {
targetPath: linkedPath ? path.resolve(path.dirname(fullPath), linkedPath) : null,
kind: "symlink",
});
continue;
}
if (entry.isDirectory()) {
out.set(entry.name, { targetPath: fullPath, kind: "directory" });
continue;
}
out.set(entry.name, { targetPath: fullPath, kind: "file" });
}
return out;
}
async function buildOpenCodeSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveOpenCodeSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
const entries: AdapterSkillEntry[] = [];
const warnings: string[] = [
"OpenCode currently uses the shared Claude skills home (~/.claude/skills).",
];
for (const available of availableEntries) {
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;
if (installedEntry?.targetPath === available.source) {
managed = true;
state = desired ? "installed" : "stale";
detail = "Installed in the shared Claude/OpenCode skills home.";
} else if (installedEntry) {
state = "external";
detail = desired
? "Skill name is occupied by an external installation in the shared skills home."
: "Installed outside Paperclip management in the shared skills home.";
} else if (desired) {
state = "missing";
detail = "Configured but not currently linked into the shared Claude/OpenCode skills home.";
}
entries.push({
key: available.key,
runtimeName: available.runtimeName,
desired,
managed,
state,
sourcePath: available.source,
targetPath: path.join(skillsHome, available.runtimeName),
detail,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
});
}
for (const desiredSkill of desiredSkills) {
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
sourcePath: null,
targetPath: null,
detail: "Paperclip cannot find this skill in the local runtime skills directory.",
});
}
for (const [name, installedEntry] of installed.entries()) {
if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
entries.push({
key: name,
runtimeName: name,
desired: false,
managed: false,
state: "external",
sourcePath: null,
targetPath: installedEntry.targetPath ?? path.join(skillsHome, name),
detail: "Installed outside Paperclip management in the shared skills home.",
});
}
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
return buildPersistentSkillSnapshot({
adapterType: "opencode_local",
supported: true,
mode: "persistent",
availableEntries,
desiredSkills,
entries,
warnings,
};
installed,
skillsHome,
locationLabel: "~/.claude/skills",
installedDetail: "Installed in the shared Claude/OpenCode skills home.",
missingDetail: "Configured but not currently linked into the shared Claude/OpenCode skills home.",
externalConflictDetail: "Skill name is occupied by an external installation in the shared skills home.",
externalDetail: "Installed outside Paperclip management in the shared skills home.",
warnings: [
"OpenCode currently uses the shared Claude skills home (~/.claude/skills).",
],
});
}
export async function listOpenCodeSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

110
packages/adapters/pi-local/src/server/skills.ts
View file

@ -4,12 +4,13 @@ import path from "node:path";
import { fileURLToPath } from "node:url";
import type {
AdapterSkillContext,
AdapterSkillEntry,
AdapterSkillSnapshot,
} from "@paperclipai/adapter-utils";
import {
buildPersistentSkillSnapshot,
ensurePaperclipSkillSymlink,
readPaperclipRuntimeSkillEntries,
readInstalledSkillTargets,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
@ -29,111 +30,22 @@ function resolvePiSkillsHome(config: Record<string, unknown>) {
return path.join(home, ".pi", "agent", "skills");
}
async function readInstalledSkillTargets(skillsHome: string) {
const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
const out = new Map<string, { targetPath: string | null; kind: "symlink" | "directory" | "file" }>();
for (const entry of entries) {
const fullPath = path.join(skillsHome, entry.name);
if (entry.isSymbolicLink()) {
const linkedPath = await fs.readlink(fullPath).catch(() => null);
out.set(entry.name, {
targetPath: linkedPath ? path.resolve(path.dirname(fullPath), linkedPath) : null,
kind: "symlink",
});
continue;
}
if (entry.isDirectory()) {
out.set(entry.name, { targetPath: fullPath, kind: "directory" });
continue;
}
out.set(entry.name, { targetPath: fullPath, kind: "file" });
}
return out;
}
async function buildPiSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolvePiSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
const entries: AdapterSkillEntry[] = [];
const warnings: string[] = [];
for (const available of availableEntries) {
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;
if (installedEntry?.targetPath === available.source) {
managed = true;
state = desired ? "installed" : "stale";
} else if (installedEntry) {
state = "external";
detail = desired
? "Skill name is occupied by an external installation."
: "Installed outside Paperclip management.";
} else if (desired) {
state = "missing";
detail = "Configured but not currently linked into the Pi skills home.";
}
entries.push({
key: available.key,
runtimeName: available.runtimeName,
desired,
managed,
state,
sourcePath: available.source,
targetPath: path.join(skillsHome, available.runtimeName),
detail,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
});
}
for (const desiredSkill of desiredSkills) {
if (availableByKey.has(desiredSkill)) continue;
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
entries.push({
key: desiredSkill,
runtimeName: null,
desired: true,
managed: true,
state: "missing",
sourcePath: null,
targetPath: null,
detail: "Paperclip cannot find this skill in the local runtime skills directory.",
});
}
for (const [name, installedEntry] of installed.entries()) {
if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
entries.push({
key: name,
runtimeName: name,
desired: false,
managed: false,
state: "external",
sourcePath: null,
targetPath: installedEntry.targetPath ?? path.join(skillsHome, name),
detail: "Installed outside Paperclip management.",
});
}
entries.sort((left, right) => left.key.localeCompare(right.key));
return {
return buildPersistentSkillSnapshot({
adapterType: "pi_local",
supported: true,
mode: "persistent",
availableEntries,
desiredSkills,
entries,
warnings,
};
installed,
skillsHome,
locationLabel: "~/.pi/agent/skills",
missingDetail: "Configured but not currently linked into the Pi skills home.",
externalConflictDetail: "Skill name is occupied by an external installation.",
externalDetail: "Installed outside Paperclip management.",
});
}
export async function listPiSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {