[codex] Add skills CLI and catalog management (#6782)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies through
company-scoped control-plane workflows.
> - Agents need reusable, inspectable skills that can be installed,
reset, audited, exported, and assigned without bespoke local setup.
> - The existing skill truth model needed cleanup so bundled skills,
optional catalog skills, runtime skills, and adapter-provided skills
have clear provenance.
> - Operators also need a practical CLI and board UI for discovering and
managing company skills.
> - This pull request adds the skills CLI, packaged skills catalog,
company skills APIs, and catalog-aware board UI.
> - The benefit is a more reusable Paperclip company setup where skills
are portable, auditable, and easier for operators and agents to manage.

## What Changed

- Added `paperclipai skills` CLI commands and coverage for catalog
listing, installing, resetting, and inspecting company skills.
- Added a packaged `@paperclipai/skills-catalog` workspace with bundled
and optional skill content plus validation/build tests.
- Added shared company-skill types and validators used across CLI,
server, and UI contracts.
- Added server catalog APIs/services for company skill catalog
operations, reset semantics, audit behavior, and portability provenance.
- Updated adapter skill handling so runtime/catalog provenance remains
explicit across local adapters.
- Added board UI support for browsing and managing catalog-backed
company skills.
- Updated docs for the skills CLI/catalog flow and the company skills
Paperclip skill reference.
- Rebased the branch onto current `paperclipai/paperclip:master`; no
`pnpm-lock.yaml`, `.github/workflows`, or migration files are included
in the final PR diff.

## Verification

- Passed: `pnpm run preflight:workspace-links && pnpm exec vitest run
cli/src/__tests__/skills.test.ts
packages/skills-catalog/src/catalog-builder.test.ts
packages/skills-catalog/src/shipped-catalog.test.ts
packages/shared/src/validators/company-skill.test.ts
packages/adapter-utils/src/server-utils.test.ts
packages/plugins/create-paperclip-plugin/src/entrypoints.test.ts
server/src/__tests__/company-skills-catalog-service.test.ts
server/src/__tests__/company-skills-routes.test.ts
server/src/__tests__/company-portability.test.ts`.
- Passed: `pnpm exec vitest run
server/src/__tests__/workspace-runtime.test.ts -t "default
branch|origin/master|symbolic-ref"`.
- Attempted: full `server/src/__tests__/workspace-runtime.test.ts`. Four
provisioning tests failed while seeding an isolated worktree database
from the local Paperclip instance because the local plugin schema dump
contains a duplicate-column foreign key
(`plugin_content_machine_18a7bc327b.content_case_signals`). The
default-branch tests touched by the rebase conflict passed in the
focused run above.
- Checked final diff: no `pnpm-lock.yaml`, no `.github/workflows`, and
no migration-file changes relative to `master`.

## Risks

- Medium: this is a broad skills/catalog change touching CLI, server
APIs, shared contracts, adapter skill sync, and UI.
- Catalog validation and reset semantics need careful reviewer attention
because they affect reusable company setup and portability.
- No database migrations are included in this PR, so there is no
migration ordering/idempotency risk in the final diff.
- No lockfile is included by design; dependency resolution will be
handled by the repository lockfile workflow.

## Model Used

- OpenAI Codex coding agent based on GPT-5, running in Paperclip via the
`codex_local` adapter with shell, git, GitHub CLI, and code-editing tool
access. Exact hosted model build/context-window metadata is not exposed
in this runtime.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run targeted tests locally and documented the local
workspace-runtime seed failure above
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, screenshots were intentionally
omitted per PAP-10124 instructions; UI behavior is covered by tests and
reviewer inspection
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

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

@@ -6,6 +6,8 @@ import { describe, expect, it } from "vitest";
 import {
   applyPaperclipWorkspaceEnv,
   appendWithByteCap,
+  buildPersistentSkillSnapshot,
+  buildRuntimeMountedSkillSnapshot,
   buildInvocationEnvForLogs,
   DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
   materializePaperclipSkillCopy,
@@ -205,6 +207,186 @@ describe("materializePaperclipSkillCopy", () => {
   });
 });
 
+describe("adapter skill snapshots", () => {
+  const requiredEntry = {
+    key: "paperclipai/paperclip/paperclip",
+    runtimeName: "paperclip",
+    source: "/runtime/paperclip",
+    required: true,
+    requiredReason: "Required for Paperclip heartbeats.",
+  };
+  const optionalEntry = {
+    key: "company/ascii-heart",
+    runtimeName: "ascii-heart",
+    source: "/runtime/ascii-heart",
+  };
+
+  it("reports runtime-mounted adapters as configured or missing without install state", () => {
+    const snapshot = buildRuntimeMountedSkillSnapshot({
+      adapterType: "codex_local",
+      availableEntries: [requiredEntry],
+      desiredSkills: [requiredEntry.key, "missing-skill"],
+      configuredDetail: "Mounted on next run.",
+    });
+
+    expect(snapshot).toMatchObject({
+      supported: true,
+      mode: "ephemeral",
+      desiredSkills: [requiredEntry.key, "missing-skill"],
+    });
+    expect(snapshot.entries).toEqual([
+      expect.objectContaining({
+        key: "missing-skill",
+        state: "missing",
+        origin: "external_unknown",
+        desired: true,
+      }),
+      expect.objectContaining({
+        key: requiredEntry.key,
+        state: "configured",
+        origin: "paperclip_required",
+        required: true,
+        detail: "Mounted on next run.",
+      }),
+    ]);
+  });
+
+  it("reports source-missing company runtime skills without orphan warnings", () => {
+    const snapshot = buildRuntimeMountedSkillSnapshot({
+      adapterType: "codex_local",
+      availableEntries: [{
+        key: "company/example/reflection-coach",
+        runtimeName: "reflection-coach--abc123",
+        source: "/paperclip/skills/example/__runtime__/reflection-coach--abc123",
+        sourceStatus: "missing",
+        missingDetail: "Company skill exists, but its local source is missing.",
+      }],
+      desiredSkills: ["company/example/reflection-coach"],
+      configuredDetail: "Mounted on next run.",
+    });
+
+    expect(snapshot.warnings).toEqual([]);
+    expect(snapshot.entries).toEqual([
+      expect.objectContaining({
+        key: "company/example/reflection-coach",
+        state: "missing",
+        origin: "company_managed",
+        sourcePath: null,
+        detail: "Company skill exists, but its local source is missing.",
+      }),
+    ]);
+  });
+
+  it("keeps unsupported runtime-mounted adapters in tracked-only state", () => {
+    const snapshot = buildRuntimeMountedSkillSnapshot({
+      adapterType: "acpx_local",
+      availableEntries: [requiredEntry],
+      desiredSkills: [requiredEntry.key],
+      configuredDetail: "Mounted on next run.",
+      mode: "unsupported",
+      unsupportedDetail: "Tracked only.",
+    });
+
+    expect(snapshot.supported).toBe(false);
+    expect(snapshot.mode).toBe("unsupported");
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: requiredEntry.key,
+      desired: true,
+      state: "available",
+      detail: "Tracked only.",
+    }));
+  });
+
+  it("can surface read-only external skills for runtime-mounted adapters", () => {
+    const snapshot = buildRuntimeMountedSkillSnapshot({
+      adapterType: "claude_local",
+      availableEntries: [requiredEntry],
+      desiredSkills: [requiredEntry.key],
+      configuredDetail: "Mounted on next run.",
+      externalInstalled: new Map([
+        ["crack-python", { targetPath: "/home/me/.claude/skills/crack-python", kind: "directory" }],
+      ]),
+      externalLocationLabel: "~/.claude/skills",
+      externalDetail: "Installed outside Paperclip management in the Claude skills home.",
+    });
+
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: "crack-python",
+      runtimeName: "crack-python",
+      state: "external",
+      managed: false,
+      origin: "user_installed",
+      locationLabel: "~/.claude/skills",
+      readOnly: true,
+    }));
+  });
+
+  it("reports persistent adapter installed, stale, external, and missing states", () => {
+    const snapshot = buildPersistentSkillSnapshot({
+      adapterType: "cursor",
+      availableEntries: [requiredEntry, optionalEntry],
+      desiredSkills: [requiredEntry.key, "missing-skill"],
+      installed: new Map([
+        ["paperclip", { targetPath: "/runtime/paperclip", kind: "symlink" }],
+        ["ascii-heart", { targetPath: "/other/ascii-heart", kind: "directory" }],
+        ["old-managed", { targetPath: "/runtime/old-managed", kind: "symlink" }],
+      ]),
+      skillsHome: "/home/me/.cursor/skills",
+      locationLabel: "~/.cursor/skills",
+      installedDetail: "Installed in the Cursor skills home.",
+      missingDetail: "Configured but not linked.",
+      externalConflictDetail: "Name occupied externally.",
+      externalDetail: "Installed outside Paperclip management.",
+    });
+
+    expect(snapshot.mode).toBe("persistent");
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: requiredEntry.key,
+      state: "installed",
+      managed: true,
+      origin: "paperclip_required",
+    }));
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: optionalEntry.key,
+      state: "external",
+      managed: false,
+      detail: "Installed outside Paperclip management.",
+    }));
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: "missing-skill",
+      state: "missing",
+      origin: "external_unknown",
+    }));
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: "old-managed",
+      state: "external",
+      origin: "user_installed",
+    }));
+  });
+
+  it("reports stale managed persistent skills when Paperclip owns an undesired available skill", () => {
+    const snapshot = buildPersistentSkillSnapshot({
+      adapterType: "cursor",
+      availableEntries: [optionalEntry],
+      desiredSkills: [],
+      installed: new Map([
+        ["ascii-heart", { targetPath: "/runtime/ascii-heart", kind: "symlink" }],
+      ]),
+      skillsHome: "/home/me/.cursor/skills",
+      missingDetail: "Configured but not linked.",
+      externalConflictDetail: "Name occupied externally.",
+      externalDetail: "Installed outside Paperclip management.",
+    });
+
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: optionalEntry.key,
+      desired: false,
+      state: "stale",
+      managed: true,
+    }));
+  });
+});
+
 describe("runChildProcess", () => {
   it("does not arm a timeout when timeoutSec is 0", async () => {
     const result = await runChildProcess(

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

@@ -133,6 +133,8 @@ export interface PaperclipSkillEntry {
   key: string;
   runtimeName: string;
   source: string;
+  sourceStatus?: "available" | "missing";
+  missingDetail?: string | null;
   required?: boolean;
   requiredReason?: string | null;
 }
@@ -161,6 +163,22 @@ interface PersistentSkillSnapshotOptions {
   warnings?: string[];
 }
 
+interface RuntimeMountedSkillSnapshotOptions {
+  adapterType: string;
+  availableEntries: PaperclipSkillEntry[];
+  desiredSkills: string[];
+  configuredDetail: string | ((entry: PaperclipSkillEntry) => string | null);
+  missingDetail?: string;
+  mode?: "ephemeral" | "unsupported";
+  supported?: boolean;
+  unsupportedDetail?: string | ((entry: PaperclipSkillEntry) => string | null);
+  warnings?: string[];
+  externalInstalled?: Map<string, InstalledSkillTarget>;
+  externalLocationLabel?: string | null;
+  externalDetail?: string;
+  skillsHome?: string;
+}
+
 function normalizePathSlashes(value: string): string {
   return value.replaceAll("\\", "/");
 }
@@ -193,6 +211,26 @@ function buildManagedSkillOrigin(entry: { required?: boolean }): Pick<
   };
 }
 
+function isPaperclipSkillSourceMissing(entry: PaperclipSkillEntry) {
+  return entry.sourceStatus === "missing";
+}
+
+function resolvePaperclipSkillMissingDetail(
+  entry: PaperclipSkillEntry,
+  fallback: string,
+) {
+  return entry.missingDetail?.trim() || fallback;
+}
+
+function resolveSkillDetail(
+  detail: string | ((entry: PaperclipSkillEntry) => string | null) | null | undefined,
+  entry: PaperclipSkillEntry,
+): string | null {
+  if (typeof detail === "function") return detail(entry);
+  if (typeof detail === "string") return detail;
+  return null;
+}
+
 function resolveInstalledEntryTarget(
   skillsHome: string,
   entryName: string,
@@ -1381,6 +1419,120 @@ export async function readInstalledSkillTargets(skillsHome: string): Promise<Map
   return out;
 }
 
+export function buildRuntimeMountedSkillSnapshot(
+  options: RuntimeMountedSkillSnapshotOptions,
+): AdapterSkillSnapshot {
+  const {
+    adapterType,
+    availableEntries,
+    desiredSkills,
+    configuredDetail,
+    missingDetail = "Paperclip cannot find this skill in the local runtime skills directory.",
+    mode = "ephemeral",
+    externalInstalled,
+    externalLocationLabel,
+    externalDetail = "Installed outside Paperclip management.",
+    skillsHome,
+  } = options;
+  const supported = options.supported ?? mode !== "unsupported";
+  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
+  const desiredSet = new Set(desiredSkills);
+  const entries: AdapterSkillEntry[] = [];
+  const warnings = [...(options.warnings ?? [])];
+
+  for (const available of availableEntries) {
+    const desired = desiredSet.has(available.key);
+    if (isPaperclipSkillSourceMissing(available)) {
+      entries.push({
+        key: available.key,
+        runtimeName: available.runtimeName,
+        desired,
+        managed: true,
+        state: "missing",
+        sourcePath: null,
+        targetPath: null,
+        detail: resolvePaperclipSkillMissingDetail(available, missingDetail),
+        required: Boolean(available.required),
+        requiredReason: available.requiredReason ?? null,
+        ...buildManagedSkillOrigin(available),
+      });
+      continue;
+    }
+
+    const configured = supported && mode === "ephemeral" && desired;
+    entries.push({
+      key: available.key,
+      runtimeName: available.runtimeName,
+      desired,
+      managed: true,
+      state: configured ? "configured" : "available",
+      sourcePath: available.source,
+      targetPath: null,
+      detail: desired
+        ? configured
+          ? resolveSkillDetail(configuredDetail, available)
+          : resolveSkillDetail(
+              options.unsupportedDetail
+                ?? "Desired state is stored in Paperclip only; this adapter cannot apply skills at runtime.",
+              available,
+            )
+        : null,
+      required: Boolean(available.required),
+      requiredReason: available.requiredReason ?? null,
+      ...buildManagedSkillOrigin(available),
+    });
+  }
+
+  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: missingDetail,
+      origin: "external_unknown",
+      originLabel: "External or unavailable",
+      readOnly: false,
+    });
+  }
+
+  if (externalInstalled) {
+    for (const [name, installedEntry] of externalInstalled.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: skillLocationLabel(externalLocationLabel),
+        readOnly: true,
+        sourcePath: null,
+        targetPath: installedEntry.targetPath ?? (skillsHome ? path.join(skillsHome, name) : null),
+        detail: externalDetail,
+      });
+    }
+  }
+
+  entries.sort((left, right) => left.key.localeCompare(right.key));
+
+  return {
+    adapterType,
+    supported,
+    mode,
+    desiredSkills,
+    entries,
+    warnings,
+  };
+}
+
 export function buildPersistentSkillSnapshot(
   options: PersistentSkillSnapshotOptions,
 ): AdapterSkillSnapshot {
@@ -1404,6 +1556,26 @@ export function buildPersistentSkillSnapshot(
   for (const available of availableEntries) {
     const installedEntry = installed.get(available.runtimeName) ?? null;
     const desired = desiredSet.has(available.key);
+    if (isPaperclipSkillSourceMissing(available)) {
+      entries.push({
+        key: available.key,
+        runtimeName: available.runtimeName,
+        desired,
+        managed: true,
+        state: "missing",
+        sourcePath: null,
+        targetPath: path.join(skillsHome, available.runtimeName),
+        detail: resolvePaperclipSkillMissingDetail(
+          available,
+          missingDetail,
+        ),
+        required: Boolean(available.required),
+        requiredReason: available.requiredReason ?? null,
+        ...buildManagedSkillOrigin(available),
+      });
+      continue;
+    }
+
     let state: AdapterSkillEntry["state"] = "available";
     let managed = false;
     let detail: string | null = null;
@@ -1496,6 +1668,11 @@ function normalizeConfiguredPaperclipRuntimeSkills(value: unknown): PaperclipSki
       key,
       runtimeName,
       source,
+      sourceStatus: entry.sourceStatus === "missing" ? "missing" : "available",
+      missingDetail:
+        typeof entry.missingDetail === "string" && entry.missingDetail.trim().length > 0
+          ? entry.missingDetail.trim()
+          : null,
       required: asBoolean(entry.required, false),
       requiredReason:
         typeof entry.requiredReason === "string" && entry.requiredReason.trim().length > 0

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

@@ -2,10 +2,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
   AdapterSkillContext,
-  AdapterSkillEntry,
   AdapterSkillSnapshot,
 } from "@paperclipai/adapter-utils";
 import {
+  buildRuntimeMountedSkillSnapshot,
   readPaperclipRuntimeSkillEntries,
   resolvePaperclipDesiredSkillNames,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -35,9 +35,7 @@ function unsupportedDetail(): string {
 async function buildAcpxSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
   const acpxAgent = normalizeAcpxSkillAgent(config);
   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 supported = acpxAgent !== "custom";
   const warnings: string[] = supported
     ? []
@@ -45,53 +43,16 @@ async function buildAcpxSkillSnapshot(config: Record<string, unknown>): Promise<
         "Custom ACP commands do not expose a Paperclip skill integration contract yet; selected skills are tracked only.",
       ];
 
-  const entries: AdapterSkillEntry[] = availableEntries.map((entry) => {
-    const desired = desiredSet.has(entry.key);
-    return {
-      key: entry.key,
-      runtimeName: entry.runtimeName,
-      desired,
-      managed: true,
-      state: desired ? "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: desired ? (supported ? configuredDetail(acpxAgent) : unsupportedDetail()) : null,
-      required: Boolean(entry.required),
-      requiredReason: entry.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",
-      origin: "external_unknown",
-      originLabel: "External or unavailable",
-      readOnly: false,
-      sourcePath: null,
-      targetPath: null,
-      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
-    });
-  }
-
-  entries.sort((left, right) => left.key.localeCompare(right.key));
-
-  return {
+  return buildRuntimeMountedSkillSnapshot({
     adapterType: "acpx_local",
+    availableEntries,
+    desiredSkills,
     supported,
     mode: supported ? "ephemeral" : "unsupported",
-    desiredSkills,
-    entries,
+    configuredDetail: configuredDetail(acpxAgent),
+    unsupportedDetail: unsupportedDetail(),
     warnings,
-  };
+  });
 }
 
 export async function listAcpxSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

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

@@ -3,10 +3,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
   AdapterSkillContext,
-  AdapterSkillEntry,
   AdapterSkillSnapshot,
 } from "@paperclipai/adapter-utils";
 import {
+  buildRuntimeMountedSkillSnapshot,
   readPaperclipRuntimeSkillEntries,
   readInstalledSkillTargets,
   resolvePaperclipDesiredSkillNames,
@@ -30,76 +30,19 @@ function resolveClaudeSkillsHome(config: Record<string, unknown>) {
 
 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)
-      ? "Will be materialized into the stable Paperclip-managed Claude prompt bundle on the next run."
-      : null,
-    required: Boolean(entry.required),
-    requiredReason: entry.requiredReason ?? null,
-  }));
-  const warnings: string[] = [];
-
-  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",
-      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 {
+  return buildRuntimeMountedSkillSnapshot({
     adapterType: "claude_local",
-    supported: true,
-    mode: "ephemeral",
+    availableEntries,
     desiredSkills,
-    entries,
-    warnings,
-  };
+    configuredDetail: "Will be materialized into the stable Paperclip-managed Claude prompt bundle on the next run.",
+    externalInstalled: installed,
+    externalLocationLabel: "~/.claude/skills",
+    externalDetail: "Installed outside Paperclip management in the Claude skills home.",
+    skillsHome,
+  });
 }
 
 export async function listClaudeSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

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

@@ -2,10 +2,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
   AdapterSkillContext,
-  AdapterSkillEntry,
   AdapterSkillSnapshot,
 } from "@paperclipai/adapter-utils";
 import {
+  buildRuntimeMountedSkillSnapshot,
   readPaperclipRuntimeSkillEntries,
   resolvePaperclipDesiredSkillNames,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -16,56 +16,13 @@ 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 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)
-      ? "Will be linked into the effective CODEX_HOME/skills/ directory on the next run."
-      : null,
-    required: Boolean(entry.required),
-    requiredReason: entry.requiredReason ?? null,
-  }));
-  const warnings: string[] = [];
-
-  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",
-      origin: "external_unknown",
-      originLabel: "External or unavailable",
-      readOnly: false,
-      sourcePath: null,
-      targetPath: null,
-      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
-    });
-  }
-
-  entries.sort((left, right) => left.key.localeCompare(right.key));
-
-  return {
+  return buildRuntimeMountedSkillSnapshot({
     adapterType: "codex_local",
-    supported: true,
-    mode: "ephemeral",
+    availableEntries,
     desiredSkills,
-    entries,
-    warnings,
-  };
+    configuredDetail: "Will be linked into the effective CODEX_HOME/skills/ directory on the next run.",
+  });
 }
 
 export async function listCodexSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

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

@@ -2,10 +2,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
   AdapterSkillContext,
-  AdapterSkillEntry,
   AdapterSkillSnapshot,
 } from "@paperclipai/adapter-utils";
 import {
+  buildRuntimeMountedSkillSnapshot,
   readPaperclipRuntimeSkillEntries,
   resolvePaperclipDesiredSkillNames,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -16,56 +16,13 @@ async function buildGrokSkillSnapshot(
   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 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)
-      ? "Will be copied into `.claude/skills` in the execution workspace on the next run."
-      : null,
-    required: Boolean(entry.required),
-    requiredReason: entry.requiredReason ?? null,
-  }));
-  const warnings: string[] = [];
-
-  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",
-      origin: "external_unknown",
-      originLabel: "External or unavailable",
-      readOnly: false,
-      sourcePath: null,
-      targetPath: null,
-      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
-    });
-  }
-
-  entries.sort((left, right) => left.key.localeCompare(right.key));
-
-  return {
+  return buildRuntimeMountedSkillSnapshot({
     adapterType: "grok_local",
-    supported: true,
-    mode: "ephemeral",
+    availableEntries,
     desiredSkills,
-    entries,
-    warnings,
-  };
+    configuredDetail: "Will be copied into `.claude/skills` in the execution workspace on the next run.",
+  });
 }
 
 export async function listGrokSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

packages/plugins/create-paperclip-plugin/README.md

@@ -34,7 +34,7 @@ Inside this repo, the generated package uses `@paperclipai/plugin-sdk` via `work
 Outside this repo, the scaffold snapshots `@paperclipai/plugin-sdk` from your local Paperclip checkout into a `.paperclip-sdk/` tarball and points the generated package at that local file by default. You can override the SDK source explicitly:
 
 ```bash
-node packages/plugins/create-paperclip-plugin/dist/index.js @acme/my-plugin \
+node packages/plugins/create-paperclip-plugin/dist/bin.js @acme/my-plugin \
   --output /absolute/path/to/plugins \
   --sdk-path /absolute/path/to/paperclip/packages/plugins/sdk
 ```

packages/plugins/create-paperclip-plugin/package.json

@@ -13,7 +13,7 @@
   },
   "type": "module",
   "bin": {
-    "create-paperclip-plugin": "./dist/index.js"
+    "create-paperclip-plugin": "./dist/bin.js"
   },
   "exports": {
     ".": "./src/index.ts"
@@ -21,7 +21,7 @@
   "publishConfig": {
     "access": "public",
     "bin": {
-      "create-paperclip-plugin": "./dist/index.js"
+      "create-paperclip-plugin": "./dist/bin.js"
     },
     "exports": {
       ".": {
@@ -38,6 +38,7 @@
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",
+    "test": "pnpm -w exec vitest run --root packages/plugins/create-paperclip-plugin --config vitest.config.ts",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

packages/plugins/create-paperclip-plugin/src/bin.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { scaffoldPluginProject, type ScaffoldPluginOptions } from "./index.js";
+
+interface RunCliDeps {
+  cwd?: string;
+  stdout?: (message: string) => void;
+  stderr?: (message: string) => void;
+  exit?: (code: number) => never;
+}
+
+function parseArg(argv: string[], name: string): string | undefined {
+  const index = argv.indexOf(name);
+  if (index === -1) return undefined;
+  return argv[index + 1];
+}
+
+/** Convert `@scope/name` to an output directory basename (`name`). */
+function packageToDirName(pluginName: string): string {
+  return pluginName.replace(/^@[^/]+\//, "");
+}
+
+/** CLI wrapper for `scaffoldPluginProject`. */
+export function runCli(argv = process.argv, deps: RunCliDeps = {}): string | undefined {
+  const pluginName = argv[2];
+  const stderr = deps.stderr ?? console.error;
+  const stdout = deps.stdout ?? console.log;
+  const exit = deps.exit ?? process.exit;
+
+  if (!pluginName) {
+    stderr("Usage: create-paperclip-plugin <name> [--template default|connector|workspace] [--output <dir>] [--sdk-path <paperclip-sdk-path>]");
+    exit(1);
+  }
+
+  const template = (parseArg(argv, "--template") ?? "default") as ScaffoldPluginOptions["template"];
+  const outputRoot = parseArg(argv, "--output") ?? deps.cwd ?? process.cwd();
+  const targetDir = path.resolve(outputRoot, packageToDirName(pluginName));
+
+  const out = scaffoldPluginProject({
+    pluginName,
+    outputDir: targetDir,
+    template,
+    displayName: parseArg(argv, "--display-name"),
+    description: parseArg(argv, "--description"),
+    author: parseArg(argv, "--author"),
+    category: parseArg(argv, "--category") as ScaffoldPluginOptions["category"] | undefined,
+    sdkPath: parseArg(argv, "--sdk-path"),
+  });
+
+  stdout(`Created plugin scaffold at ${out}`);
+  return out;
+}
+
+function isMainModule(): boolean {
+  const entrypoint = process.argv[1];
+  return entrypoint ? import.meta.url === pathToFileURL(entrypoint).href : false;
+}
+
+if (isMainModule()) {
+  runCli();
+}

packages/plugins/create-paperclip-plugin/src/entrypoints.test.ts

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+const tempDirs: string[] = [];
+
+function makeTempDir(): string {
+  const dir = fs.mkdtempSync(path.join(process.cwd(), ".tmp-create-paperclip-plugin-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("create-paperclip-plugin entrypoints", () => {
+  it("keeps src/index.ts import-safe when process.argv points at another bundled CLI", async () => {
+    const originalArgv = process.argv;
+    const outputRoot = makeTempDir();
+
+    try {
+      process.argv = [process.execPath, path.resolve("cli/dist/index.js"), "demo-plugin", "--output", outputRoot];
+      const library = await import("./index.js");
+
+      expect(library.scaffoldPluginProject).toBeTypeOf("function");
+      expect(fs.existsSync(path.join(outputRoot, "demo-plugin"))).toBe(false);
+    } finally {
+      process.argv = originalArgv;
+    }
+  });
+
+  it("runs scaffolding from src/bin.ts", async () => {
+    const { runCli } = await import("./bin.js");
+    const outputRoot = makeTempDir();
+    const stdout: string[] = [];
+    const outputDir = path.join(outputRoot, "demo-plugin");
+
+    const result = runCli(
+      [
+        process.execPath,
+        "create-paperclip-plugin",
+        "demo-plugin",
+        "--output",
+        outputRoot,
+        "--sdk-path",
+        path.resolve("packages/plugins/sdk"),
+      ],
+      {
+        stdout: (message) => stdout.push(message),
+        stderr: (message) => {
+          throw new Error(message);
+        },
+        exit: (code) => {
+          throw new Error(`unexpected exit ${code}`);
+        },
+      },
+    );
+
+    expect(result).toBe(outputDir);
+    expect(stdout).toEqual([`Created plugin scaffold at ${outputDir}`]);
+    expect(JSON.parse(fs.readFileSync(path.join(outputDir, "package.json"), "utf8"))).toMatchObject({
+      name: "demo-plugin",
+      paperclipPlugin: {
+        manifest: "./dist/manifest.js",
+        worker: "./dist/worker.js",
+        ui: "./dist/ui/",
+      },
+    });
+  });
+});

packages/plugins/create-paperclip-plugin/src/index.ts

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
@@ -699,41 +698,3 @@ paperclipai plugin install ${shellQuote(toPosixPath(outputDir))}
 
   return outputDir;
 }
-
-function parseArg(name: string): string | undefined {
-  const index = process.argv.indexOf(name);
-  if (index === -1) return undefined;
-  return process.argv[index + 1];
-}
-
-/** CLI wrapper for `scaffoldPluginProject`. */
-function runCli() {
-  const pluginName = process.argv[2];
-  if (!pluginName) {
-    // eslint-disable-next-line no-console
-    console.error("Usage: create-paperclip-plugin <name> [--template default|connector|workspace] [--output <dir>] [--sdk-path <paperclip-sdk-path>]");
-    process.exit(1);
-  }
-
-  const template = (parseArg("--template") ?? "default") as PluginTemplate;
-  const outputRoot = parseArg("--output") ?? process.cwd();
-  const targetDir = path.resolve(outputRoot, packageToDirName(pluginName));
-
-  const out = scaffoldPluginProject({
-    pluginName,
-    outputDir: targetDir,
-    template,
-    displayName: parseArg("--display-name"),
-    description: parseArg("--description"),
-    author: parseArg("--author"),
-    category: parseArg("--category") as ScaffoldPluginOptions["category"] | undefined,
-    sdkPath: parseArg("--sdk-path"),
-  });
-
-  // eslint-disable-next-line no-console
-  console.log(`Created plugin scaffold at ${out}`);
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  runCli();
-}

packages/plugins/create-paperclip-plugin/tsconfig.json

@@ -5,5 +5,6 @@
     "rootDir": "src",
     "types": ["node"]
   },
-  "include": ["src"]
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
 }

packages/plugins/create-paperclip-plugin/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+  },
+});

packages/shared/src/index.ts

@@ -296,6 +296,13 @@ export type {
   CompanySkillUsageAgent,
   CompanySkillDetail,
   CompanySkillUpdateStatus,
+  CompanySkillAuditSeverity,
+  CompanySkillAuditVerdict,
+  CompanySkillUpdateHoldReason,
+  CompanySkillAuditFinding,
+  CompanySkillAuditResult,
+  CompanySkillInstallUpdateRequest,
+  CompanySkillResetRequest,
   CompanySkillImportRequest,
   CompanySkillImportResult,
   CompanySkillProjectScanRequest,
@@ -305,6 +312,14 @@ export type {
   CompanySkillCreateRequest,
   CompanySkillFileDetail,
   CompanySkillFileUpdateRequest,
+  CatalogSkillKind,
+  CatalogSkillFileKind,
+  CatalogSkillFile,
+  CatalogSkill,
+  CatalogSkillListQuery,
+  CatalogSkillFileDetail,
+  CompanySkillInstallCatalogRequest,
+  CompanySkillInstallCatalogResult,
   AgentSkillSyncMode,
   AgentSkillState,
   AgentSkillOrigin,
@@ -1060,6 +1075,8 @@ export {
   companySkillUsageAgentSchema,
   companySkillDetailSchema,
   companySkillUpdateStatusSchema,
+  companySkillAuditFindingSchema,
+  companySkillAuditResultSchema,
   companySkillImportSchema,
   companySkillProjectScanRequestSchema,
   companySkillProjectScanSkippedSchema,
@@ -1068,6 +1085,15 @@ export {
   companySkillCreateSchema,
   companySkillFileDetailSchema,
   companySkillFileUpdateSchema,
+  catalogSkillKindSchema,
+  catalogSkillFileSchema,
+  catalogSkillSchema,
+  catalogSkillListQuerySchema,
+  catalogSkillFileDetailSchema,
+  companySkillInstallCatalogSchema,
+  companySkillInstallCatalogResultSchema,
+  companySkillInstallUpdateSchema,
+  companySkillResetSchema,
   portabilityIncludeSchema,
   portabilityEnvInputSchema,
   portabilityCompanyManifestEntrySchema,

packages/shared/src/types/company-skill.ts

@@ -51,6 +51,10 @@ export interface CompanySkillListItem {
   sourceLabel: string | null;
   sourceBadge: CompanySkillSourceBadge;
   sourcePath: string | null;
+  catalogKind: "bundled" | "optional" | null;
+  originHash: string | null;
+  packageName: string | null;
+  packageVersion: string | null;
 }
 
 export interface CompanySkillUsageAgent {
@@ -84,6 +88,49 @@ export interface CompanySkillUpdateStatus {
   currentRef: string | null;
   latestRef: string | null;
   hasUpdate: boolean;
+  installedHash: string | null;
+  originHash: string | null;
+  userModifiedAt: string | null;
+  updateHoldReason: CompanySkillUpdateHoldReason | null;
+  auditVerdict: CompanySkillAuditVerdict | null;
+  auditCodes: string[];
+}
+
+export type CompanySkillAuditSeverity = "warning" | "error";
+
+export type CompanySkillAuditVerdict = "pass" | "warning" | "fail";
+
+export type CompanySkillUpdateHoldReason =
+  | "local_modifications"
+  | "audit_hard_stop"
+  | "origin_unavailable"
+  | "compatibility_invalid"
+  | "operator_hold";
+
+export interface CompanySkillAuditFinding {
+  code: string;
+  severity: CompanySkillAuditSeverity;
+  message: string;
+  path: string | null;
+}
+
+export interface CompanySkillAuditResult {
+  skillId: string;
+  installedHash: string | null;
+  originHash: string | null;
+  verdict: CompanySkillAuditVerdict;
+  codes: string[];
+  findings: CompanySkillAuditFinding[];
+  scannedAt: string;
+  scanVersion: string;
+}
+
+export interface CompanySkillInstallUpdateRequest {
+  force?: boolean;
+}
+
+export interface CompanySkillResetRequest {
+  force?: boolean;
 }
 
 export interface CompanySkillImportRequest {
@@ -155,3 +202,64 @@ export interface CompanySkillFileUpdateRequest {
   path: string;
   content: string;
 }
+
+export type CatalogSkillKind = "bundled" | "optional";
+
+export type CatalogSkillFileKind = CompanySkillFileInventoryEntry["kind"];
+
+export interface CatalogSkillFile {
+  path: string;
+  kind: CatalogSkillFileKind;
+  sizeBytes: number;
+  sha256: string;
+}
+
+export interface CatalogSkill {
+  id: string;
+  key: string;
+  kind: CatalogSkillKind;
+  category: string;
+  slug: string;
+  name: string;
+  description: string;
+  path: string;
+  entrypoint: "SKILL.md";
+  trustLevel: CompanySkillTrustLevel;
+  compatibility: CompanySkillCompatibility;
+  defaultInstall: boolean;
+  recommendedForRoles: string[];
+  requires: string[];
+  tags: string[];
+  files: CatalogSkillFile[];
+  contentHash: string;
+  packageName?: string;
+  packageVersion?: string;
+}
+
+export interface CatalogSkillListQuery {
+  kind?: CatalogSkillKind;
+  category?: string;
+  q?: string;
+}
+
+export interface CatalogSkillFileDetail {
+  catalogSkillId: string;
+  path: string;
+  kind: CatalogSkillFileKind;
+  content: string;
+  language: string | null;
+  markdown: boolean;
+}
+
+export interface CompanySkillInstallCatalogRequest {
+  catalogSkillId: string;
+  slug?: string | null;
+  force?: boolean;
+}
+
+export interface CompanySkillInstallCatalogResult {
+  action: "created" | "updated" | "unchanged";
+  skill: CompanySkill;
+  catalogSkill: CatalogSkill;
+  warnings: string[];
+}

packages/shared/src/types/index.ts

@@ -51,6 +51,13 @@ export type {
   CompanySkillUsageAgent,
   CompanySkillDetail,
   CompanySkillUpdateStatus,
+  CompanySkillAuditSeverity,
+  CompanySkillAuditVerdict,
+  CompanySkillUpdateHoldReason,
+  CompanySkillAuditFinding,
+  CompanySkillAuditResult,
+  CompanySkillInstallUpdateRequest,
+  CompanySkillResetRequest,
   CompanySkillImportRequest,
   CompanySkillImportResult,
   CompanySkillProjectScanRequest,
@@ -60,6 +67,14 @@ export type {
   CompanySkillCreateRequest,
   CompanySkillFileDetail,
   CompanySkillFileUpdateRequest,
+  CatalogSkillKind,
+  CatalogSkillFileKind,
+  CatalogSkillFile,
+  CatalogSkill,
+  CatalogSkillListQuery,
+  CatalogSkillFileDetail,
+  CompanySkillInstallCatalogRequest,
+  CompanySkillInstallCatalogResult,
 } from "./company-skill.js";
 export type {
   AgentSkillSyncMode,

packages/shared/src/validators/company-skill.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it } from "vitest";
+import {
+  catalogSkillFileDetailSchema,
+  catalogSkillListQuerySchema,
+  companySkillAuditResultSchema,
+  companySkillInstallCatalogResultSchema,
+  companySkillInstallCatalogSchema,
+  companySkillInstallUpdateSchema,
+  companySkillResetSchema,
+  companySkillUpdateStatusSchema,
+} from "./company-skill.js";
+
+const catalogSkill = {
+  id: "paperclipai:bundled:software-development:review",
+  key: "paperclipai/bundled/software-development/review",
+  kind: "bundled",
+  category: "software-development",
+  slug: "review",
+  name: "review",
+  description: "Review code",
+  path: "catalog/bundled/software-development/review",
+  entrypoint: "SKILL.md",
+  trustLevel: "markdown_only",
+  compatibility: "compatible",
+  defaultInstall: false,
+  recommendedForRoles: ["engineer"],
+  requires: [],
+  tags: ["review"],
+  files: [{ path: "SKILL.md", kind: "skill", sizeBytes: 8, sha256: "abc" }],
+  contentHash: "sha256:abc",
+};
+
+const companySkill = {
+  id: "00000000-0000-4000-8000-000000000001",
+  companyId: "00000000-0000-4000-8000-000000000002",
+  key: catalogSkill.key,
+  slug: catalogSkill.slug,
+  name: catalogSkill.name,
+  description: catalogSkill.description,
+  markdown: "# Review\n",
+  sourceType: "catalog",
+  sourceLocator: "/tmp/review",
+  sourceRef: catalogSkill.contentHash,
+  trustLevel: "markdown_only",
+  compatibility: "compatible",
+  fileInventory: [{ path: "SKILL.md", kind: "skill" }],
+  metadata: {
+    sourceKind: "catalog",
+    catalogId: catalogSkill.id,
+    originHash: catalogSkill.contentHash,
+  },
+  createdAt: "2026-05-26T00:00:00.000Z",
+  updatedAt: "2026-05-26T00:00:00.000Z",
+};
+
+describe("company skill catalog validators", () => {
+  it("accepts catalog list and install request shapes", () => {
+    expect(catalogSkillListQuerySchema.parse({
+      kind: "bundled",
+      category: "software-development",
+      q: "review",
+    })).toEqual({
+      kind: "bundled",
+      category: "software-development",
+      q: "review",
+    });
+
+    expect(companySkillInstallCatalogSchema.parse({
+      catalogSkillId: catalogSkill.id,
+      slug: "team-review",
+      force: true,
+    })).toEqual({
+      catalogSkillId: catalogSkill.id,
+      slug: "team-review",
+      force: true,
+    });
+  });
+
+  it("rejects invalid catalog filter and install payloads", () => {
+    expect(() => catalogSkillListQuerySchema.parse({ kind: "external" })).toThrow();
+    expect(() => companySkillInstallCatalogSchema.parse({ force: true })).toThrow();
+  });
+
+  it("accepts catalog file and install result responses", () => {
+    expect(catalogSkillFileDetailSchema.parse({
+      catalogSkillId: catalogSkill.id,
+      path: "SKILL.md",
+      kind: "skill",
+      content: "# Review\n",
+      language: "markdown",
+      markdown: true,
+    })).toMatchObject({
+      catalogSkillId: catalogSkill.id,
+      path: "SKILL.md",
+    });
+
+    expect(companySkillInstallCatalogResultSchema.parse({
+      action: "created",
+      skill: companySkill,
+      catalogSkill,
+      warnings: [],
+    })).toMatchObject({
+      action: "created",
+      skill: {
+        key: catalogSkill.key,
+        sourceType: "catalog",
+      },
+      catalogSkill: {
+        id: catalogSkill.id,
+      },
+    });
+  });
+
+  it("accepts update status, audit, update, and reset contract shapes", () => {
+    expect(companySkillUpdateStatusSchema.parse({
+      supported: true,
+      reason: null,
+      trackingRef: catalogSkill.id,
+      currentRef: "sha256:old",
+      latestRef: catalogSkill.contentHash,
+      hasUpdate: true,
+      installedHash: "sha256:installed",
+      originHash: catalogSkill.contentHash,
+      userModifiedAt: "2026-05-26T00:00:00.000Z",
+      updateHoldReason: "local_modifications",
+      auditVerdict: "warning",
+      auditCodes: ["local_modifications"],
+    })).toMatchObject({
+      supported: true,
+      updateHoldReason: "local_modifications",
+      auditVerdict: "warning",
+    });
+
+    expect(companySkillAuditResultSchema.parse({
+      skillId: companySkill.id,
+      installedHash: "sha256:installed",
+      originHash: catalogSkill.contentHash,
+      verdict: "fail",
+      codes: ["remote_fetch_exec"],
+      findings: [{
+        code: "remote_fetch_exec",
+        severity: "error",
+        message: "Remote-fetch or dynamic execution pattern is not allowed.",
+        path: "SKILL.md",
+      }],
+      scannedAt: "2026-05-26T00:00:00.000Z",
+      scanVersion: "skills-audit-v1",
+    })).toMatchObject({
+      verdict: "fail",
+      codes: ["remote_fetch_exec"],
+    });
+
+    expect(companySkillInstallUpdateSchema.parse(undefined)).toEqual({});
+    expect(companySkillInstallUpdateSchema.parse({ force: true })).toEqual({ force: true });
+    expect(companySkillResetSchema.parse(undefined)).toEqual({});
+    expect(companySkillResetSchema.parse({ force: true })).toEqual({ force: true });
+  });
+});

packages/shared/src/validators/company-skill.ts

@@ -35,6 +35,10 @@ export const companySkillListItemSchema = companySkillSchema.extend({
   editableReason: z.string().nullable(),
   sourceLabel: z.string().nullable(),
   sourceBadge: companySkillSourceBadgeSchema,
+  catalogKind: z.enum(["bundled", "optional"]).nullable(),
+  originHash: z.string().nullable(),
+  packageName: z.string().nullable(),
+  packageVersion: z.string().nullable(),
 });
 
 export const companySkillUsageAgentSchema = z.object({
@@ -64,8 +68,46 @@ export const companySkillUpdateStatusSchema = z.object({
   currentRef: z.string().nullable(),
   latestRef: z.string().nullable(),
   hasUpdate: z.boolean(),
+  installedHash: z.string().nullable(),
+  originHash: z.string().nullable(),
+  userModifiedAt: z.string().nullable(),
+  updateHoldReason: z.enum([
+    "local_modifications",
+    "audit_hard_stop",
+    "origin_unavailable",
+    "compatibility_invalid",
+    "operator_hold",
+  ]).nullable(),
+  auditVerdict: z.enum(["pass", "warning", "fail"]).nullable(),
+  auditCodes: z.array(z.string()),
 });
 
+export const companySkillAuditFindingSchema = z.object({
+  code: z.string().min(1),
+  severity: z.enum(["warning", "error"]),
+  message: z.string().min(1),
+  path: z.string().nullable(),
+});
+
+export const companySkillAuditResultSchema = z.object({
+  skillId: z.string().uuid(),
+  installedHash: z.string().nullable(),
+  originHash: z.string().nullable(),
+  verdict: z.enum(["pass", "warning", "fail"]),
+  codes: z.array(z.string()),
+  findings: z.array(companySkillAuditFindingSchema),
+  scannedAt: z.string().min(1),
+  scanVersion: z.string().min(1),
+});
+
+export const companySkillInstallUpdateSchema = z.object({
+  force: z.boolean().optional(),
+}).default({});
+
+export const companySkillResetSchema = z.object({
+  force: z.boolean().optional(),
+}).default({});
+
 export const companySkillImportSchema = z.object({
   source: z.string().min(1),
 });
@@ -131,7 +173,70 @@ export const companySkillFileUpdateSchema = z.object({
   content: z.string(),
 });
 
+export const catalogSkillKindSchema = z.enum(["bundled", "optional"]);
+
+export const catalogSkillFileSchema = z.object({
+  path: z.string().min(1),
+  kind: z.enum(["skill", "markdown", "reference", "script", "asset", "other"]),
+  sizeBytes: z.number().int().nonnegative(),
+  sha256: z.string().min(1),
+});
+
+export const catalogSkillSchema = z.object({
+  id: z.string().min(1),
+  key: z.string().min(1),
+  kind: catalogSkillKindSchema,
+  category: z.string().min(1),
+  slug: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string(),
+  path: z.string().min(1),
+  entrypoint: z.literal("SKILL.md"),
+  trustLevel: companySkillTrustLevelSchema,
+  compatibility: companySkillCompatibilitySchema,
+  defaultInstall: z.boolean(),
+  recommendedForRoles: z.array(z.string()),
+  requires: z.array(z.string()),
+  tags: z.array(z.string()),
+  files: z.array(catalogSkillFileSchema),
+  contentHash: z.string().min(1),
+  packageName: z.string().min(1).optional(),
+  packageVersion: z.string().min(1).optional(),
+});
+
+export const catalogSkillListQuerySchema = z.object({
+  kind: catalogSkillKindSchema.optional(),
+  category: z.string().min(1).optional(),
+  q: z.string().min(1).optional(),
+});
+
+export const catalogSkillFileDetailSchema = z.object({
+  catalogSkillId: z.string().min(1),
+  path: z.string().min(1),
+  kind: z.enum(["skill", "markdown", "reference", "script", "asset", "other"]),
+  content: z.string(),
+  language: z.string().nullable(),
+  markdown: z.boolean(),
+});
+
+export const companySkillInstallCatalogSchema = z.object({
+  catalogSkillId: z.string().min(1),
+  slug: z.string().min(1).nullable().optional(),
+  force: z.boolean().optional(),
+});
+
+export const companySkillInstallCatalogResultSchema = z.object({
+  action: z.enum(["created", "updated", "unchanged"]),
+  skill: companySkillSchema,
+  catalogSkill: catalogSkillSchema,
+  warnings: z.array(z.string()),
+});
+
 export type CompanySkillImport = z.infer<typeof companySkillImportSchema>;
 export type CompanySkillProjectScan = z.infer<typeof companySkillProjectScanRequestSchema>;
 export type CompanySkillCreate = z.infer<typeof companySkillCreateSchema>;
 export type CompanySkillFileUpdate = z.infer<typeof companySkillFileUpdateSchema>;
+export type CatalogSkillListQuery = z.infer<typeof catalogSkillListQuerySchema>;
+export type CompanySkillInstallCatalog = z.infer<typeof companySkillInstallCatalogSchema>;
+export type CompanySkillInstallUpdate = z.infer<typeof companySkillInstallUpdateSchema>;
+export type CompanySkillReset = z.infer<typeof companySkillResetSchema>;

packages/shared/src/validators/index.ts

@@ -67,6 +67,8 @@ export {
   companySkillUsageAgentSchema,
   companySkillDetailSchema,
   companySkillUpdateStatusSchema,
+  companySkillAuditFindingSchema,
+  companySkillAuditResultSchema,
   companySkillImportSchema,
   companySkillProjectScanRequestSchema,
   companySkillProjectScanSkippedSchema,
@@ -75,10 +77,23 @@ export {
   companySkillCreateSchema,
   companySkillFileDetailSchema,
   companySkillFileUpdateSchema,
+  catalogSkillKindSchema,
+  catalogSkillFileSchema,
+  catalogSkillSchema,
+  catalogSkillListQuerySchema,
+  catalogSkillFileDetailSchema,
+  companySkillInstallCatalogSchema,
+  companySkillInstallCatalogResultSchema,
+  companySkillInstallUpdateSchema,
+  companySkillResetSchema,
   type CompanySkillImport,
   type CompanySkillProjectScan,
   type CompanySkillCreate,
   type CompanySkillFileUpdate,
+  type CatalogSkillListQuery,
+  type CompanySkillInstallCatalog,
+  type CompanySkillInstallUpdate,
+  type CompanySkillReset,
 } from "./company-skill.js";
 export {
   agentSkillStateSchema,

packages/skills-catalog/catalog/bundled/docs/doc-maintenance/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: doc-maintenance
+description: Keep project docs aligned with recent code and feature changes — detect drift, update affected pages, and add release-relevant notes without rewriting unchanged sections.
+key: paperclipai/bundled/docs/doc-maintenance
+recommendedForRoles:
+  - engineer
+  - product
+  - devrel
+tags:
+  - docs
+  - documentation
+  - release-notes
+---
+
+# Doc Maintenance
+
+Keep the documentation honest with minimum churn. The goal is alignment between docs and behavior, not stylistic rewrites or cosmetic re-organization. Reviewers should be able to read a diff and see "this updates docs to match recent behavior changes".
+
+## When to use
+
+- A PR or recent set of merges changed user-visible behavior: CLI flags, API shapes, default values, configuration keys, endpoints, environment variables, supported versions.
+- A user-reported bug traced back to outdated documentation.
+- A release is being cut and the docs need a pass against the merged commits.
+- A new feature shipped but only the engineer's PR description describes how to use it.
+
+## When not to use
+
+- The change is internal-only (private helper rename, refactor) with no user-visible impact.
+- You want to "improve the docs" without a behavior anchor. That is a separate scoped project, not maintenance — make a plan first.
+
+## The pass
+
+1. **Establish the baseline.** Get the commit range you are documenting against (since last release tag, since last merged-doc commit, or since a specific PR).
+2. **Enumerate user-visible changes.** Read commits and PR descriptions. List, for each change, what a user can now do differently.
+3. **Map changes to docs.** For each change, find every page that mentions the affected concept. Common targets: README, CLI reference, API reference, configuration reference, migration guide, FAQ, examples.
+4. **Update precisely.** Edit only the lines that need to change. Do not rewrap paragraphs you did not modify — it pollutes the diff.
+5. **Add new entries where needed.** New CLI flag → CLI reference entry. New env var → configuration reference entry. New endpoint → API reference entry. Don't only add it to the changelog.
+6. **Update examples and snippets.** Code blocks in docs are wrong faster than prose. Re-run any example that touches new behavior.
+7. **Write the release note.** One sentence per user-visible change. Group by Added / Changed / Fixed / Deprecated / Removed. Link to the relevant PRs and docs section.
+8. **Cross-check.** Search the docs for the old behavior wording and remove or update stragglers.
+
+## Style baseline
+
+- Voice: second person ("you can pass `--json` to ..."). Avoid "we" except in narrative pages.
+- Tense: present, not future. The behavior exists once shipped.
+- Headings: imperative ("Configure the cache") or noun-phrase ("Cache configuration"), match the surrounding page.
+- Code blocks: include the language tag so syntax highlighting works.
+- Cross-links: link the first mention of a concept on each page; do not link every occurrence.
+- Avoid promising future behavior. If something is unreleased, mark it `experimental` or omit it.
+
+## Drift detection
+
+A doc page is drifting if any of these are true:
+
+- It documents a flag, key, or endpoint that no longer exists.
+- An example does not run as written.
+- A default value in the docs does not match the code.
+- A supported-versions list excludes a version the project actually supports, or includes one it dropped.
+- A "Coming soon" section references a feature that shipped or was cancelled.
+
+When you find drift, fix it in the same pass and note it in the release note's `Fixed` group.
+
+## Release-note rules
+
+- One sentence per item. If two sentences are needed, the item is likely two items.
+- User impact first, internal cause second. `Faster cold start (avoid full bundle download on first run)` beats `Refactor bootstrap loader`.
+- Link the PR for engineering readers and the docs page for users.
+- Mark breaking changes explicitly: `**Breaking:**` prefix. Include migration steps inline or via link.
+
+## Anti-patterns
+
+- Massive doc PRs that bundle stylistic rewrites with real updates. Reviewers cannot tell which lines reflect actual behavior changes.
+- "Updated docs" commit messages with no detail. Make the commit say what changed and why.
+- Adding to the changelog without updating the reference docs the changelog points to.
+- Marking a feature as available before its code lands. Documentation must follow behavior, not promise it.

packages/skills-catalog/catalog/bundled/paperclip-operations/issue-triage/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: issue-triage
+description: Triage Paperclip inbox issues that are stale, blocked, in-review, or assigned-but-not-progressing, and decide a single next action per issue (resume, reassign, unblock, escalate, or close).
+key: paperclipai/bundled/paperclip-operations/issue-triage
+recommendedForRoles:
+  - manager
+  - ceo
+  - engineer
+tags:
+  - paperclip
+  - triage
+  - inbox
+  - workflow
+---
+
+# Issue Triage
+
+Convert a noisy inbox into a small set of clear next actions. Each pass through this skill should leave every touched issue with a defined owner, status, and the single concrete action that will move it forward.
+
+## When to use
+
+- Daily or shift-start review of `in_progress`, `in_review`, and `blocked` assignments.
+- An inbox has many open assignments and no clear priority.
+- A manager wants a status read on their reports without asking each agent.
+- You are woken by a comment that suggests an old issue stalled.
+
+## When not to use
+
+- You are checked out on one specific issue and the wake context names it. Work that issue, do not triage the whole inbox.
+- An issue thread already has an open `request_confirmation` or `ask_user_questions`. Wait for the response — re-triage is noise.
+
+## Inputs
+
+- `GET /api/agents/me/inbox-lite` for the compact assignment list.
+- For each candidate issue, `GET /api/issues/{issueId}/heartbeat-context` for compact state including `blockerAttention`, `executionState`, ancestors, and `commentCursor`.
+- Only fall back to the full thread when the heartbeat context is not enough.
+
+## Per-issue triage decision
+
+For each issue, classify into exactly one of:
+
+1. **Resume** — execution path is alive. Confirm the assignee is set and let the heartbeat continue. Do not comment.
+2. **Wake-needed** — assignee is stalled with no live continuation. Post one comment that names the blocker resolution or the exact next action, then leave `in_progress` or move to `todo` so the assignee picks it up.
+3. **Reassign** — the assignee is not the right specialty. Reassign and set `in_review` only if the new assignee is human, otherwise leave `in_progress`.
+4. **Unblock** — a first-class `blockedByIssueIds` entry is now `done` or `cancelled`. If `cancelled`, replace or remove it from `blockedByIssueIds`. The blockers-resolved wake will fire automatically when all are `done`.
+5. **Escalate** — the issue needs board, CTO, or user input. Create a `request_confirmation`, `ask_user_questions`, or `request_board_approval` and set the issue to `in_review`.
+6. **Close** — work is complete, duplicate, or no longer relevant. Set `done` or `cancelled` with a one-line reason.
+
+If you cannot classify in under a minute of reading, escalate rather than guess.
+
+## Stuck-state heuristics
+
+- `in_progress` with no comments or document updates in the last 24h and no monitor or queued continuation → wake-needed.
+- `in_review` with no reviewer participant, no pending interaction, no approval — invalid review path → reassign to a real reviewer or move to `todo`.
+- `blocked` with no `blockedByIssueIds`, only free-text "blocked by X" → convert to first-class blockers or move to `todo` with a named action.
+- `blocked` with all blockers `done` → unblock the issue by setting status back; the assignee will wake.
+- Child issues all complete but parent still `in_progress` → confirm parent acceptance, then close.
+
+## Don't-do list
+
+- Do not @-mention agents during triage; mentions cost budget. Use direct reassignment instead.
+- Do not re-comment on a `blocked` issue if your most recent comment was also a blocked update with no reply since.
+- Do not cancel cross-team issues. Reassign to the responsible manager with a comment.
+- Do not change status without a comment that explains the change.
+
+## Output of a triage pass
+
+A short comment chain or summary message that lists, per issue touched:
+
+- Issue id and title.
+- Verdict (resume / wake-needed / reassign / unblock / escalate / close).
+- The one action you took or asked for.
+
+This is the bar for "the triage is done."

packages/skills-catalog/catalog/bundled/paperclip-operations/task-planning/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: task-planning
+description: Turn a Paperclip issue or request into a structured implementation plan with child task graph, blockers, owners, and acceptance criteria, then save it as the issue `plan` document.
+key: paperclipai/bundled/paperclip-operations/task-planning
+recommendedForRoles:
+  - manager
+  - engineer
+  - product
+tags:
+  - paperclip
+  - planning
+  - issues
+  - delegation
+---
+
+# Task Planning
+
+Produce implementation plans that the Paperclip executor can actually run: explicit child issues, real blockers, named owners, and a defined acceptance bar. Avoid plans that read well but cannot be split into work.
+
+## When to use
+
+- An issue asks you to "plan", "scope", "break down", "design the rollout", "propose the work", or similar.
+- A user wants a written plan before approving implementation.
+- A manager needs to delegate non-trivial work and the shape of the work is not obvious yet.
+- You inherited an issue too large to deliver in one heartbeat and need to split it.
+
+## When not to use
+
+- The issue is a single small change you can ship in the same heartbeat. Just ship it.
+- The issue is forensic ("why did this break"). Use a diagnosis skill first; plan only after the root cause is named.
+- A current `plan` document already exists and the change is minor. Update that document; do not start fresh.
+
+## Outputs
+
+1. An updated issue document with key `plan` (markdown).
+2. A short comment on the issue that links to the plan document and names the next action.
+3. Where the plan requires approval, an issue-thread interaction of kind `request_confirmation` bound to the latest plan revision.
+
+Do not create implementation subtasks until the plan is accepted.
+
+## Plan structure
+
+Required sections, in order:
+
+1. **Goal** — one paragraph. What changes for the user, the operator, or the system once this work lands.
+2. **Context reviewed** — bullet list of documents, files, and prior issues you read. Lets reviewers spot missing inputs.
+3. **Constraints and non-goals** — what must hold (compatibility, security, performance) and what this plan deliberately will not do.
+4. **Approach** — the chosen path, with a short rationale. If you considered alternatives, name them and why you rejected them.
+5. **Work breakdown** — ordered list of child issues. Each child has:
+   - Title in imperative form.
+   - Owner specialty (Engineer, QA, Designer, Security, DevRel, Manager, etc.).
+   - Scope and deliverables.
+   - Acceptance criteria.
+   - Blocks/blocked-by relationships expressed by phase letter or child title.
+6. **Acceptance** — the bar for the parent issue. How the user knows the whole thing is done.
+7. **Risks and mitigations** — short list. Skip if there are none.
+8. **Deferrals** — what is intentionally pushed to follow-up issues, with why.
+
+## Rules of thumb for splitting
+
+- One child issue, one specialty. If two specialties have to coordinate inside the same issue, split it.
+- One child issue, one acceptance verdict. If a reviewer would say "this is half done", split it.
+- A child must be checkout-able by the owner from its title and description alone. Reviewers should not have to re-read the parent plan to understand a child.
+- Order children by real blocker chains, not by author preference. Parallel children should explicitly say `blockers: none`.
+- Avoid `polish` or `cleanup` child issues without acceptance criteria — they never close.
+
+## Filing the plan
+
+Use the Paperclip API to write the plan document, then comment:
+
+- `PUT /api/issues/{issueId}/documents/plan` with the markdown body. If `plan` already exists, include the latest `baseRevisionId`.
+- `POST /api/issues/{issueId}/comments` with a short summary that links the plan: `/<prefix>/issues/<issue-id>#document-plan`.
+- If approval is required: `POST /api/issues/{issueId}/interactions` with `kind: request_confirmation`, `targetRevisionId` set to the new plan revision, `continuationPolicy: wake_assignee`, and `idempotencyKey: "confirmation:{issueId}:plan:{revisionId}"`.
+- Set the issue to `in_review` after creating the confirmation. Stay assigned so the acceptance wakes the planner.
+
+When the plan is accepted, see the companion skill for converting accepted plans into Paperclip executable tasks.
+
+## Anti-patterns
+
+- Plan disguised as a description edit. Use the `plan` document.
+- "Phases A–Z" with no work breakdown inside the phases.
+- Children with descriptions that say "see parent" — they fail at delegation time.
+- Acceptance written as "code review approval". Reviewers need a behavior bar, not a process bar.
+- Plans that bury blocker chains in prose. Use explicit blocked-by lines.

packages/skills-catalog/catalog/bundled/quality/qa-acceptance/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: qa-acceptance
+description: Produce QA acceptance criteria and a manual validation plan for a feature change — golden path, edge cases, error states, performance limits, and explicit pass/fail evidence.
+key: paperclipai/bundled/quality/qa-acceptance
+recommendedForRoles:
+  - qa
+  - engineer
+  - product
+tags:
+  - qa
+  - acceptance
+  - validation
+  - testing
+---
+
+# QA Acceptance
+
+Write acceptance criteria that a reviewer can run against the running app and decide pass or fail without asking the author. The criteria are the contract — automated tests cover correctness, QA covers feature-level behavior.
+
+## When to use
+
+- A feature change is heading to QA and needs a written validation plan.
+- A reviewer is asked to verify a PR that touches user-visible behavior.
+- An incident postmortem requires a regression check before reopen-prevention.
+- A release candidate needs a pre-cut smoke pass.
+
+## When not to use
+
+- The change is unit-test-only (utility refactor, internal naming). Acceptance criteria are unnecessary churn.
+- You are asked to write tests against API contracts. Use contract testing, not feature QA.
+
+## Acceptance criteria format
+
+Each criterion is a single, independently-verifiable statement:
+
+```md
+- **Given** <starting state>, **when** <action>, **then** <observable outcome>.
+```
+
+Example:
+
+```md
+- **Given** a CSV export with 0 rows, **when** the user clicks Export, **then** the file downloads with only the header row and the UI shows "Exported 0 rows".
+```
+
+Avoid criteria that combine multiple `when`s or `then`s. Split them.
+
+## What every plan must cover
+
+1. **Golden path.** The most common successful flow, end to end.
+2. **Empty and minimum states.** Zero items, one item, missing optional inputs.
+3. **Boundary inputs.** Max length strings, max numeric values, unicode, RTL text where applicable.
+4. **Error states.** Network failure, permission denied, validation failures, conflict (409), not found (404).
+5. **Concurrency and ordering.** Two users acting at once, race against background jobs, refresh during mutation.
+6. **Performance envelope.** The largest realistic input the change must handle without UI hangs or timeouts.
+7. **Backward compatibility.** Existing data, existing URLs, persisted user preferences continue to work.
+8. **Telemetry and audit.** Events, logs, or activity entries the change is supposed to emit.
+
+If a section is genuinely not applicable, write "N/A: <why>" — do not silently omit.
+
+## Evidence
+
+Each criterion needs evidence on the verification pass:
+
+- Screenshot or short clip for UI behavior.
+- Copied console / network output for API behavior.
+- Log snippet or activity row for telemetry.
+- Timing measurement for performance criteria.
+
+"Looks good to me" without evidence is not a pass.
+
+## Quarantine and follow-up
+
+- A failing criterion blocks acceptance unless explicitly waived by the owner with a tracked follow-up issue.
+- "Known issue" without a linked follow-up is not a waiver.
+- If you add a new criterion mid-pass, restart the pass — partial coverage hides regressions.
+
+## Handoff back to the author
+
+Return the validation plan with three sections:
+
+- **Pass.** Criteria that passed, with one-line evidence summaries.
+- **Fail.** Criteria that failed, with the exact reproduction.
+- **Blocked.** Criteria you could not run, with why.
+
+The author owns turning failures into either fixes or accepted deferrals.
+
+## Anti-patterns
+
+- Acceptance phrased as test plan ("write a Cypress test for X"). Acceptance is what is true after the change ships; tests are how you check.
+- Criteria that depend on inspecting implementation details (selectors, query plans). Stay observable.
+- Long checklists with no priority. Mark must-pass criteria distinctly from nice-to-have.
+- Validation reports that say "passed" with no evidence. Reviewers cannot audit those.

packages/skills-catalog/catalog/bundled/software-development/github-pr-workflow/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: github-pr-workflow
+description: Prepare a GitHub pull request from a feature branch — branch hygiene, commit shape, title/body, verification notes, screenshots for UI work, and replies to review comments.
+key: paperclipai/bundled/software-development/github-pr-workflow
+recommendedForRoles:
+  - engineer
+tags:
+  - github
+  - pull-requests
+  - code-review
+  - release
+---
+
+# GitHub Pull Request Workflow
+
+Ship a PR a reviewer can land without follow-up clarifying questions. The aim is high signal in the title and body, evidence the change works, and clean replies when feedback comes in.
+
+## When to use
+
+- You are about to open a PR for a change that is functionally complete.
+- A reviewer left comments and you need to respond and push fixes.
+- A PR has been open more than a day and needs to be brought back into shape (stale conflicts, missing description, missing verification).
+
+## When not to use
+
+- The change is not yet functionally complete. Finish the work first; draft PRs that bounce on review are noise.
+- The repository uses a non-GitHub forge. Adjust to that forge's conventions; do not force GitHub-isms.
+
+## Branch hygiene before opening
+
+- Rebase or merge from the target base so the diff is current.
+- Squash WIP commits into reviewable units. Prefer one commit per logical change; do not force one-commit-per-PR if the work is genuinely multi-step.
+- Confirm tests, typecheck, and lint pass locally. Note any deliberate skips in the PR body.
+- Remove debug prints, commented-out code, and `TODO` markers that are not tracked.
+
+## PR title
+
+- Imperative mood, under 70 characters.
+- Lead with the user-visible change, not the file touched. `Allow CSV export from reports table` beats `Update reports.tsx`.
+- If the repo uses an issue prefix convention (`PAP-1234:`, `[security]`), follow it.
+- No trailing period.
+
+## PR body
+
+Use this structure:
+
+```md
+## Summary
+- 1–3 bullets describing what changed and why.
+
+## Implementation notes
+- Anything non-obvious in the diff: trade-offs, dropped alternatives, gotchas.
+- Migration or config implications.
+
+## Verification
+- The exact commands or steps you ran.
+- Screenshots or short clips for UI changes (required if pixels moved).
+- Edge cases you exercised by hand.
+
+## Risk and rollback
+- What breaks if this is reverted, and how to revert cleanly.
+```
+
+Skip the `Risk and rollback` section only for clearly trivial PRs (typos, docs).
+
+## Verification evidence
+
+- Tests passing in CI is necessary, not sufficient. Reviewers also need to know the change behaves correctly end to end.
+- For UI work, include screenshots of the golden path and one edge case. Tag dark and light mode if the project supports both.
+- For migrations, include a dry-run plan and reversal steps.
+- For performance changes, include a before/after measurement, not adjectives.
+
+## Replying to review comments
+
+- Reply on every comment, even with just "fixed in <commit-sha>" — silent fixes leave the reviewer guessing.
+- Push fixes as new commits while review is active; do not amend during review unless the reviewer agrees.
+- If you disagree with feedback, say so with one sentence of rationale and let the reviewer decide. Don't escalate over comments.
+- Re-request review explicitly after pushing changes.
+
+## Merge checklist
+
+- All required checks green.
+- All review comments resolved.
+- PR title/body still accurate (update if scope changed mid-review).
+- Linked issue moves to `in_review` or `done` per project convention.
+- Delete the branch after merge unless it is a long-lived integration branch.
+
+## Anti-patterns
+
+- PR description that says "see commits". Reviewers should not need to read the log.
+- Mixing refactor and behavior change in the same PR with no separation in the body.
+- "Address feedback" commits that bundle unrelated edits. One commit per round of feedback is fine; one commit for everything in flight is not.
+- Force-pushing during active review without telling the reviewer.

packages/skills-catalog/catalog/optional/browser/agent-browser/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: agent-browser
+description: Drive a real browser to inspect or interact with a web page or app — navigate, take screenshots, read console and network, fill simple forms — for verification tasks, not unattended automation.
+key: paperclipai/optional/browser/agent-browser
+recommendedForRoles:
+  - qa
+  - engineer
+  - researcher
+tags:
+  - browser
+  - puppeteer
+  - playwright
+  - verification
+---
+
+# Agent Browser
+
+Use a controlled browser to verify behavior, capture evidence, or extract information from web pages that a static fetch cannot reach (SPAs, login-gated pages, dynamic content). This skill is about supervised verification, not unattended scraping.
+
+## When to use
+
+- You need a screenshot of a deployed page or a local dev server to confirm a UI change.
+- You need to read JavaScript-rendered content that `curl`/`wget` will not see.
+- A user reports a UI bug and you need to reproduce it interactively to capture console errors, network requests, or layout state.
+- You need to walk through a short flow (load page, click, observe) to verify acceptance criteria.
+
+## When not to use
+
+- The page is reachable as static HTML. Use `curl`/HTTP fetch — it is cheaper, faster, and more reliable.
+- The task is unattended large-scale scraping. That belongs to a dedicated scraper with rate limits, robots.txt handling, and a real user agent policy — not this skill.
+- The site is behind authentication you do not own credentials for, or whose terms of service prohibit automation.
+- The site involves sensitive accounts (banking, healthcare, government) where automation risks lockout or compliance issues.
+
+## Before launching the browser
+
+- Confirm the URL and what state should be true after navigation.
+- Decide what evidence is needed: full-page screenshot, viewport screenshot, console log, network trace, HTML snapshot, extracted text.
+- Decide the viewport size that matters for the task (mobile vs desktop). Default to a desktop size unless the task is mobile-specific.
+- For local dev servers, confirm the server is running and the port is what you expect.
+
+## Driving the browser
+
+A typical verification session:
+
+1. **Launch with a real-looking user agent** when the target is the public internet; an unrealistic UA flags automation traffic.
+2. **Set a sane viewport** (e.g., 1366×768 desktop, 390×844 iPhone-ish).
+3. **Navigate and wait for the right signal.** Prefer waiting for a specific selector or network-idle over arbitrary sleeps.
+4. **Capture evidence immediately** after the wait condition succeeds, before any interaction perturbs the state.
+5. **Interact deliberately.** One click at a time, with a wait between actions; re-screenshot after each meaningful state change.
+6. **Read the console and network panels** for unexpected errors, 4xx/5xx responses, or slow requests.
+7. **Close the browser cleanly** when done. Long-running browser sessions leak memory and hold ports.
+
+## What evidence to record
+
+For a verification task, deliver:
+
+- A full-page or viewport screenshot of each meaningful state.
+- The console log, filtered to warnings/errors.
+- Any non-2xx network response with the URL, status, and a short response body excerpt.
+- A short narration: "Navigated to X, observed Y, clicked Z, observed W."
+
+For a UI bug repro, also record:
+
+- The exact reproduction steps the user can follow.
+- Viewport size and (where relevant) device pixel ratio.
+- Whether the bug reproduces on first load vs after interaction.
+
+## Login-gated pages
+
+- Prefer programmatic auth (API token, magic link) over UI login.
+- If UI login is the only path, the user must provide credentials explicitly for this run. Never reuse credentials outside the session.
+- Do not store credentials in the session log, screenshot, or returned output.
+
+## Performance and politeness
+
+- Throttle to one navigation per few seconds when touching shared infra.
+- Respect `robots.txt` for public sites you are inspecting at any volume.
+- Cancel navigations if a page exceeds a reasonable timeout (e.g., 30s); the page is broken or rate-limiting you.
+- Do not retry forever on failure. Retry once with a longer timeout, then escalate.
+
+## Common failure modes
+
+- **Selector not found.** Page changed, or you are waiting before render. Take a screenshot to see actual state; adjust the selector.
+- **Click does nothing.** The element is offscreen, covered by a modal, or in a shadow DOM. Scroll into view or pierce the shadow root.
+- **Headless detection.** Some sites detect headless Chrome and serve a different page. Use a non-headless mode or a fingerprint-realistic configuration only when authorized.
+- **Cross-origin iframe blocking.** Iframes you do not own cannot be inspected; the page must offer the data outside the iframe or the task is infeasible.
+
+## Anti-patterns
+
+- Long unsupervised browser sessions that drift from the original task.
+- Scraping behind authentication you do not own.
+- Captioning a screenshot with "looks good" without saying what state was loaded and what selectors confirmed it.
+- Treating a passing screenshot as proof of correctness across viewports you did not actually test.

packages/skills-catalog/catalog/optional/content/release-announcement/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: release-announcement
+description: Write a release announcement — changelog, blog post, in-app note, or social post — that leads with user impact, names the audience, and includes upgrade/migration steps without filler.
+key: paperclipai/optional/content/release-announcement
+recommendedForRoles:
+  - devrel
+  - product
+  - writer
+tags:
+  - release
+  - changelog
+  - announcement
+  - communication
+---
+
+# Release Announcement
+
+Write the channel-appropriate announcement for a release without churn. Different surfaces need different shapes: a changelog entry is not a blog post is not a social card. The bar is: a reader of the chosen surface can decide in under 30 seconds whether this release affects them, and if so what to do.
+
+## When to use
+
+- A version, feature, or fix is shipping and needs writeup for at least one surface.
+- A previously private feature is going GA.
+- A breaking change needs broadcast before users hit it.
+
+## When not to use
+
+- An internal-only change with no user impact. Update internal docs; do not announce.
+- The release is incomplete (still in active development). Wait until it ships, even if marketing wants the post.
+
+## Determine the audience and channel first
+
+| Audience | Best channel | Tone |
+|---|---|---|
+| Existing power users | Changelog, in-app note | Terse, factual, links |
+| Engineering teams adopting your API | Release notes, dev blog | Examples, migration steps, version pins |
+| Prospective customers | Landing page, marketing blog | Story arc, problem → solution, social proof |
+| Broad audience | Social post, email newsletter | One-sentence pitch, link to depth |
+| Internal team | Slack/Discord post | What changed, who to ping if it breaks |
+
+Pick the audience for *this* writeup. One release often needs several writeups; do not blend them.
+
+## Universal structure
+
+Whatever the channel, lead with:
+
+1. **What changed.** One sentence in the user's vocabulary.
+2. **Who it affects.** Which user role / use case.
+3. **What to do.** Migrate now / opt-in / no action needed.
+
+Everything else is depth that supports those three.
+
+## Channel templates
+
+### Changelog entry (terse)
+
+```md
+## v1.42.0 — 2026-05-26
+
+### Added
+- <feature> — <one-line user benefit>. ([#1234](link))
+
+### Changed
+- <change> — <one-line impact>. ([#1235](link))
+
+### Fixed
+- <bug> — <one-line user-visible symptom>. ([#1236](link))
+
+### Deprecated
+- <thing>. Replaced by <thing>. Removal planned for v<x>.
+
+### Breaking
+- <change>. **Migration:** <one-line> or <link to guide>.
+```
+
+### Release notes (for adopters)
+
+Same as changelog, plus:
+
+- Migration guide section with before/after code.
+- Compatibility table (versions, runtimes, OS).
+- Known issues and workarounds.
+- Acknowledgements (contributors, reporters of fixed bugs).
+
+### Dev blog post (300–800 words)
+
+- **Hook (1 paragraph):** the problem the release solves, in a real-world scenario.
+- **What's new (3–5 bullets with sub-paragraphs):** features, with one code or screenshot example each.
+- **Upgrade (1 paragraph):** how to upgrade, what to check.
+- **What's next:** one sentence about the next direction. Avoid promises.
+
+### In-app note
+
+- 1 sentence.
+- 1 link.
+- Dismiss after seen.
+
+### Social post
+
+- 1 sentence pitch.
+- 1 link.
+- 1 image or short clip.
+- No threadbait. If it needs a thread, write a blog post instead.
+
+## Writing rules
+
+- Lead with the user, not the team. `You can now export to CSV` beats `We've added CSV export`.
+- Numbers beat adjectives. `60% faster cold start` beats `much faster`. Cite the methodology.
+- Show, don't just tell. One code snippet, one screenshot — more is noise.
+- Date the post. Undated release content rots fastest.
+- Link the migration path explicitly. Do not bury it.
+- Mark breaking changes with `**Breaking:**` prefix. Repeat in the email/social channel.
+
+## Avoid
+
+- "We are excited to announce" filler.
+- Lists of changes that mix user-visible and internal items.
+- Marketing claims without a way to verify.
+- Promised dates for unshipped work.
+- Pre-announcing something the team has not yet committed to ship.
+
+## Post-publish checklist
+
+- Changelog is in source control alongside the release.
+- Blog post date matches actual ship date.
+- All links work (release tag, PRs, docs sections).
+- Breaking changes are also in the upgrade guide, not only the post.
+- Internal team is notified before the public post goes live, not after.

packages/skills-catalog/catalog/optional/product/design-critique/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: design-critique
+description: Give a structured product design critique — user job clarity, hierarchy, affordance, error states, accessibility, and consistency — focused on what to change, in what order, and why.
+key: paperclipai/optional/product/design-critique
+recommendedForRoles:
+  - designer
+  - product
+  - engineer
+tags:
+  - design
+  - product
+  - ux
+  - review
+---
+
+# Product Design Critique
+
+A structured critique pass for a screen, flow, or component. The output is a prioritized list of changes a designer or engineer can act on — not adjectives. Critique is not redesign; recommend, do not rebuild.
+
+## When to use
+
+- A designer or engineer asks for feedback on a screen, mock, or live UI.
+- A feature is shipping and someone wants a final UX read.
+- A flow is suspected of causing user drop-off and you want a pre-research read before instrumentation.
+
+## When not to use
+
+- The user wants a redesign. That is a design project, not a critique.
+- The work is so early that no concrete artifact exists. Sketch with them instead of critiquing air.
+- You have no context on the user job. Ask for it first; design critique without user context devolves into taste.
+
+## Pre-critique context
+
+Before opening a screen, get:
+
+- **Who is the user.** Specific role and competence, not "users".
+- **What job they are doing on this screen.** One sentence.
+- **What success looks like.** What the user can do after this screen that they could not before.
+- **Where this screen sits in the larger flow.** What precedes and follows.
+
+If any of these is missing, ask. Critique without these is opinion.
+
+## The pass (in order)
+
+1. **Clarity of the user job.**
+   - Within 3 seconds of opening, is it obvious what this screen is for?
+   - Does the primary action match the user's actual job, or a designer's preferred path?
+
+2. **Visual hierarchy.**
+   - The most important thing on the screen should be the most prominent (size, weight, position, color).
+   - Secondary actions should look secondary. Tertiary should be findable but not loud.
+   - Headings should chunk content into the right groups for the task.
+
+3. **Affordance and signifiers.**
+   - Clickable things look clickable.
+   - Disabled things look disabled and explain why on hover/focus.
+   - Drag, scroll, or swipe interactions are discoverable, not hidden.
+
+4. **States.**
+   - Empty state (no data) is designed, not a blank rectangle.
+   - Loading state communicates progress, not just spins.
+   - Error states say what went wrong and what to do next, in the user's words.
+   - Success state confirms without celebrating banal actions.
+
+5. **Inputs and forms.**
+   - Labels visible, not just placeholders.
+   - Validation runs at the right time (on blur, not on every keystroke unless the user is in a known-format field).
+   - Required fields marked.
+   - Field order matches the user's mental order, not the database order.
+
+6. **Accessibility.**
+   - Sufficient color contrast (WCAG AA at minimum; AAA where reasonable).
+   - Focus order is logical for keyboard navigation.
+   - Interactive elements are reachable without a mouse.
+   - Critical information is not color-only (icons, text, position back it up).
+   - Touch targets at least 44×44 px on mobile.
+
+7. **Consistency.**
+   - Tokens, components, and patterns match the rest of the product.
+   - "Borrowed" patterns from other products are intentional, not accidental drift.
+
+8. **Copy.**
+   - Buttons are verbs that name the outcome ("Save changes" beats "Submit").
+   - Microcopy explains, does not decorate.
+   - Tone matches the product voice.
+
+9. **Edge cases.**
+   - Long content (long names, many items, RTL languages).
+   - Tiny content (one item, zero items).
+   - Slow network and offline behavior.
+   - Permissions denied.
+
+## Output format
+
+Group findings by severity, then by category. Each finding is one issue and one suggested fix.
+
+```md
+## Design critique: <screen name>
+
+### Must-fix (blocks ship)
+- **<category>:** <one-line issue>. **Try:** <one-line suggestion>.
+
+### Should-fix (before broader rollout)
+- **<category>:** <one-line issue>. **Try:** <one-line suggestion>.
+
+### Nice-to-fix (when there's room)
+- **<category>:** <one-line issue>. **Try:** <one-line suggestion>.
+
+### Strengths to keep
+- <one-line thing the design got right>
+```
+
+Always include the "strengths to keep" section. It is not flattery — it is signal to the designer about what not to change in the next round.
+
+## Anti-patterns
+
+- "I would do it differently" without saying what or why. That is preference, not critique.
+- Long critiques that bury must-fix items under nice-to-haves.
+- Suggesting net-new features under the guise of a critique.
+- Ignoring user context and grading on taste.
+- Treating a critique as approval. State approval explicitly if asked; otherwise critique is feedback, not sign-off.

packages/skills-catalog/generated/catalog.json

@@ -0,0 +1,285 @@
+{
+  "schemaVersion": 1,
+  "packageName": "@paperclipai/skills-catalog",
+  "packageVersion": "0.3.1",
+  "generatedAt": "2026-05-28T03:02:49.579Z",
+  "skills": [
+    {
+      "id": "paperclipai:bundled:docs:doc-maintenance",
+      "key": "paperclipai/bundled/docs/doc-maintenance",
+      "kind": "bundled",
+      "category": "docs",
+      "slug": "doc-maintenance",
+      "name": "doc-maintenance",
+      "description": "Keep project docs aligned with recent code and feature changes — detect drift, update affected pages, and add release-relevant notes without rewriting unchanged sections.",
+      "path": "catalog/bundled/docs/doc-maintenance",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "engineer",
+        "product",
+        "devrel"
+      ],
+      "requires": [],
+      "tags": [
+        "docs",
+        "documentation",
+        "release-notes"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 4478,
+          "sha256": "fb0353386c5e5e5e13bcbb3233f044e3dccecf371f429d6328f26c26d7cb6169"
+        }
+      ],
+      "contentHash": "sha256:2e02299210fd17c1fe1867b4ee8c144a11b6fe1fe481f83b8268cfbaaf10f9aa"
+    },
+    {
+      "id": "paperclipai:bundled:paperclip-operations:issue-triage",
+      "key": "paperclipai/bundled/paperclip-operations/issue-triage",
+      "kind": "bundled",
+      "category": "paperclip-operations",
+      "slug": "issue-triage",
+      "name": "issue-triage",
+      "description": "Triage Paperclip inbox issues that are stale, blocked, in-review, or assigned-but-not-progressing, and decide a single next action per issue (resume, reassign, unblock, escalate, or close).",
+      "path": "catalog/bundled/paperclip-operations/issue-triage",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "manager",
+        "ceo",
+        "engineer"
+      ],
+      "requires": [],
+      "tags": [
+        "paperclip",
+        "triage",
+        "inbox",
+        "workflow"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 4042,
+          "sha256": "df5bdc8bf5e017b7ba5f70a4b5323fad51d0c323278f386580f26cf43ad09160"
+        }
+      ],
+      "contentHash": "sha256:88dc13560371fb364963782cb4f6eeb4090fcde92ee3774479428ed6b90e11c1"
+    },
+    {
+      "id": "paperclipai:bundled:paperclip-operations:task-planning",
+      "key": "paperclipai/bundled/paperclip-operations/task-planning",
+      "kind": "bundled",
+      "category": "paperclip-operations",
+      "slug": "task-planning",
+      "name": "task-planning",
+      "description": "Turn a Paperclip issue or request into a structured implementation plan with child task graph, blockers, owners, and acceptance criteria, then save it as the issue `plan` document.",
+      "path": "catalog/bundled/paperclip-operations/task-planning",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "manager",
+        "engineer",
+        "product"
+      ],
+      "requires": [],
+      "tags": [
+        "paperclip",
+        "planning",
+        "issues",
+        "delegation"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 4649,
+          "sha256": "2ff61e12dfaa4cf8cc548529fd176f55f1b1f5292ff9dd3eb2cb331417ab5e4e"
+        }
+      ],
+      "contentHash": "sha256:4fb46a4bcefad4fd46fae48c433ee497112509a8e19fb8a7745ead44d219b498"
+    },
+    {
+      "id": "paperclipai:bundled:quality:qa-acceptance",
+      "key": "paperclipai/bundled/quality/qa-acceptance",
+      "kind": "bundled",
+      "category": "quality",
+      "slug": "qa-acceptance",
+      "name": "qa-acceptance",
+      "description": "Produce QA acceptance criteria and a manual validation plan for a feature change — golden path, edge cases, error states, performance limits, and explicit pass/fail evidence.",
+      "path": "catalog/bundled/quality/qa-acceptance",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "qa",
+        "engineer",
+        "product"
+      ],
+      "requires": [],
+      "tags": [
+        "qa",
+        "acceptance",
+        "validation",
+        "testing"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 3861,
+          "sha256": "c631b437ab26d104af6cdb963d8f679a9341439041b3cb3ec8835f4ff551b378"
+        }
+      ],
+      "contentHash": "sha256:32372dacaf62e93454b9855968c4eec96456ba78b509f450b3dfaa48e31ef356"
+    },
+    {
+      "id": "paperclipai:bundled:software-development:github-pr-workflow",
+      "key": "paperclipai/bundled/software-development/github-pr-workflow",
+      "kind": "bundled",
+      "category": "software-development",
+      "slug": "github-pr-workflow",
+      "name": "github-pr-workflow",
+      "description": "Prepare a GitHub pull request from a feature branch — branch hygiene, commit shape, title/body, verification notes, screenshots for UI work, and replies to review comments.",
+      "path": "catalog/bundled/software-development/github-pr-workflow",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "engineer"
+      ],
+      "requires": [],
+      "tags": [
+        "github",
+        "pull-requests",
+        "code-review",
+        "release"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 3970,
+          "sha256": "f498ec4ebb1779dea37adeb1db8a8b22316282798e35ee02e2fc5ff627d7e261"
+        }
+      ],
+      "contentHash": "sha256:90f278c89aa0711be150c1cd2456ca25620d02f36995b113ca9837d756a37f6c"
+    },
+    {
+      "id": "paperclipai:optional:browser:agent-browser",
+      "key": "paperclipai/optional/browser/agent-browser",
+      "kind": "optional",
+      "category": "browser",
+      "slug": "agent-browser",
+      "name": "agent-browser",
+      "description": "Drive a real browser to inspect or interact with a web page or app — navigate, take screenshots, read console and network, fill simple forms — for verification tasks, not unattended automation.",
+      "path": "catalog/optional/browser/agent-browser",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "qa",
+        "engineer",
+        "researcher"
+      ],
+      "requires": [],
+      "tags": [
+        "browser",
+        "puppeteer",
+        "playwright",
+        "verification"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 5133,
+          "sha256": "362f7b9d02297782bc6f0c093f495b8a0304a75bcf4b42e5c280a42b1f757b7d"
+        }
+      ],
+      "contentHash": "sha256:eabb2c9f7b5e1a27ebb1e05a711d61433a266478154cd671a685e99e67aadea2"
+    },
+    {
+      "id": "paperclipai:optional:content:release-announcement",
+      "key": "paperclipai/optional/content/release-announcement",
+      "kind": "optional",
+      "category": "content",
+      "slug": "release-announcement",
+      "name": "release-announcement",
+      "description": "Write a release announcement — changelog, blog post, in-app note, or social post — that leads with user impact, names the audience, and includes upgrade/migration steps without filler.",
+      "path": "catalog/optional/content/release-announcement",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "devrel",
+        "product",
+        "writer"
+      ],
+      "requires": [],
+      "tags": [
+        "release",
+        "changelog",
+        "announcement",
+        "communication"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 4416,
+          "sha256": "062810ac34e9edc89efa701fec2eee60f16949d1944cc2cae49803cb91e8cbf4"
+        }
+      ],
+      "contentHash": "sha256:f22a9ed696e6614c6db2757a149f48b3295e81f78c27d065d9cb164cf4f8a9bd"
+    },
+    {
+      "id": "paperclipai:optional:product:design-critique",
+      "key": "paperclipai/optional/product/design-critique",
+      "kind": "optional",
+      "category": "product",
+      "slug": "design-critique",
+      "name": "design-critique",
+      "description": "Give a structured product design critique — user job clarity, hierarchy, affordance, error states, accessibility, and consistency — focused on what to change, in what order, and why.",
+      "path": "catalog/optional/product/design-critique",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "designer",
+        "product",
+        "engineer"
+      ],
+      "requires": [],
+      "tags": [
+        "design",
+        "product",
+        "ux",
+        "review"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 4851,
+          "sha256": "022e619baf6cc25725946279cb8052d22af090dd6cd6dc8c20f17867f71a5d8e"
+        }
+      ],
+      "contentHash": "sha256:429f94df398a0697042b5bbe4755b1ff1a230aa5f41d99118ad37493ac65d21c"
+    }
+  ]
+}

packages/skills-catalog/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@paperclipai/skills-catalog",
+  "version": "0.3.1",
+  "license": "MIT",
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "packages/skills-catalog"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts",
+    "./catalog.json": "./generated/catalog.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/src/index.d.ts",
+        "import": "./dist/src/index.js"
+      },
+      "./types": {
+        "types": "./dist/src/types.d.ts",
+        "import": "./dist/src/types.js"
+      },
+      "./catalog.json": "./dist/generated/catalog.json"
+    },
+    "main": "./dist/src/index.js",
+    "types": "./dist/src/index.d.ts"
+  },
+  "files": [
+    "catalog",
+    "dist",
+    "generated"
+  ],
+  "scripts": {
+    "build": "pnpm run build:manifest && tsc -p tsconfig.json",
+    "build:manifest": "node ../../cli/node_modules/tsx/dist/cli.mjs scripts/build-catalog-manifest.ts",
+    "clean": "rm -rf dist",
+    "test": "pnpm -w exec vitest run --root packages/skills-catalog --config vitest.config.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "validate": "node ../../cli/node_modules/tsx/dist/cli.mjs scripts/validate-catalog.ts"
+  }
+}

packages/skills-catalog/scripts/build-catalog-manifest.ts

@@ -0,0 +1,15 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { writeCatalogManifest } from "../src/catalog-builder.js";
+
+const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const result = await writeCatalogManifest(packageDir);
+
+if (result.errors.length > 0) {
+  for (const error of result.errors) {
+    console.error(`- ${error}`);
+  }
+  process.exitCode = 1;
+} else {
+  console.log(`Wrote generated/catalog.json with ${result.manifest.skills.length} catalog skills.`);
+}

packages/skills-catalog/scripts/validate-catalog.ts

@@ -0,0 +1,15 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { validateCatalog } from "../src/catalog-builder.js";
+
+const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const result = await validateCatalog(packageDir);
+
+if (result.errors.length > 0) {
+  for (const error of result.errors) {
+    console.error(`- ${error}`);
+  }
+  process.exitCode = 1;
+} else {
+  console.log(`Catalog manifest is valid with ${result.manifest.skills.length} catalog skills.`);
+}

packages/skills-catalog/src/catalog-builder.test.ts

@@ -0,0 +1,165 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  buildCatalogManifest,
+  formatCatalogManifest,
+  validateCatalog,
+} from "./catalog-builder.js";
+
+const tempDirs: string[] = [];
+
+describe("skills catalog manifest", () => {
+  afterEach(async () => {
+    await Promise.all(tempDirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+  });
+
+  it("builds stable manifest entries from catalog skill directories", async () => {
+    const packageDir = await createCatalogPackage();
+    await writeSkill(packageDir, "bundled", "software-development", "github-pr-workflow", {
+      frontmatter: [
+        "name: GitHub PR Workflow",
+        "description: Prepare pull requests and verification notes.",
+        "key: paperclipai/bundled/software-development/github-pr-workflow",
+        "recommendedForRoles:",
+        "  - engineer",
+        "tags:",
+        "  - github",
+        "  - pull-requests",
+      ],
+      files: {
+        "references/checklist.md": "# Checklist\n",
+      },
+    });
+
+    const result = await buildCatalogManifest({
+      packageDir,
+      generatedAt: "2026-05-26T00:00:00.000Z",
+    });
+
+    expect(result.errors).toEqual([]);
+    expect(result.manifest.skills).toHaveLength(1);
+    expect(result.manifest.skills[0]).toMatchObject({
+      id: "paperclipai:bundled:software-development:github-pr-workflow",
+      key: "paperclipai/bundled/software-development/github-pr-workflow",
+      kind: "bundled",
+      category: "software-development",
+      slug: "github-pr-workflow",
+      name: "GitHub PR Workflow",
+      trustLevel: "markdown_only",
+      compatibility: "compatible",
+      recommendedForRoles: ["engineer"],
+      tags: ["github", "pull-requests"],
+    });
+    expect(result.manifest.skills[0]!.files.map((file) => file.path)).toEqual([
+      "SKILL.md",
+      "references/checklist.md",
+    ]);
+    expect(result.manifest.skills[0]!.contentHash).toMatch(/^sha256:[a-f0-9]{64}$/);
+  });
+
+  it("reports frontmatter, directory, uniqueness, and inventory errors together", async () => {
+    const packageDir = await createCatalogPackage();
+    await writeSkill(packageDir, "bundled", "Bad_Category", "duplicate", {
+      frontmatter: [
+        "name: Duplicate",
+        "key: paperclipai/bundled/software-development/other",
+        "recommendedForRoles: engineer",
+      ],
+    });
+    await writeSkill(packageDir, "optional", "software-development", "duplicate", {
+      frontmatter: [
+        "name: Duplicate Optional",
+        "description: Optional duplicate slug.",
+      ],
+    });
+    await fs.mkdir(path.join(packageDir, "catalog", "bundled", "software-development", "missing-skill"), {
+      recursive: true,
+    });
+    await fs.mkdir(path.join(packageDir, "catalog", "misc"), { recursive: true });
+    await fs.writeFile(path.join(packageDir, "catalog", "misc", "SKILL.md"), "# Misplaced\n", "utf8");
+
+    const result = await buildCatalogManifest({
+      packageDir,
+      generatedAt: "2026-05-26T00:00:00.000Z",
+    });
+
+    expect(result.errors).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("catalog/misc/SKILL.md is not under catalog/<bundled|optional>/<category>/<slug>/SKILL.md"),
+        expect.stringContaining("catalog/bundled/software-development/missing-skill is missing SKILL.md"),
+        expect.stringContaining("has invalid category"),
+        expect.stringContaining("frontmatter must include description"),
+        expect.stringContaining("key must be paperclipai/bundled/Bad_Category/duplicate"),
+        expect.stringContaining("field recommendedForRoles must be an array of strings"),
+        expect.stringContaining("Duplicate catalog slug \"duplicate\""),
+      ]),
+    );
+  });
+
+  it("detects stale generated manifests", async () => {
+    const packageDir = await createCatalogPackage();
+    await writeSkill(packageDir, "bundled", "software-development", "review", {
+      frontmatter: [
+        "name: Review",
+        "description: Review implementation work.",
+      ],
+    });
+    await fs.mkdir(path.join(packageDir, "generated"), { recursive: true });
+    await fs.writeFile(
+      path.join(packageDir, "generated", "catalog.json"),
+      formatCatalogManifest({
+        schemaVersion: 1,
+        packageName: "@paperclipai/skills-catalog",
+        packageVersion: "0.3.1",
+        generatedAt: "2026-05-26T00:00:00.000Z",
+        skills: [],
+      }),
+      "utf8",
+    );
+
+    const result = await validateCatalog(packageDir);
+
+    expect(result.errors).toContain(
+      "generated/catalog.json is stale. Run pnpm --filter @paperclipai/skills-catalog build:manifest.",
+    );
+  });
+});
+
+async function createCatalogPackage() {
+  const packageDir = await fs.mkdtemp(path.join(os.tmpdir(), "skills-catalog-"));
+  tempDirs.push(packageDir);
+  await fs.mkdir(path.join(packageDir, "catalog", "bundled"), { recursive: true });
+  await fs.mkdir(path.join(packageDir, "catalog", "optional"), { recursive: true });
+  await fs.writeFile(
+    path.join(packageDir, "package.json"),
+    JSON.stringify({ version: "0.3.1" }),
+    "utf8",
+  );
+  return packageDir;
+}
+
+async function writeSkill(
+  packageDir: string,
+  kind: "bundled" | "optional",
+  category: string,
+  slug: string,
+  options: {
+    frontmatter: string[];
+    files?: Record<string, string>;
+  },
+) {
+  const skillDir = path.join(packageDir, "catalog", kind, category, slug);
+  await fs.mkdir(skillDir, { recursive: true });
+  await fs.writeFile(
+    path.join(skillDir, "SKILL.md"),
+    `---\n${options.frontmatter.join("\n")}\n---\n\nUse this skill.\n`,
+    "utf8",
+  );
+  for (const [relativePath, content] of Object.entries(options.files ?? {})) {
+    const filePath = path.join(skillDir, relativePath);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content, "utf8");
+  }
+}

packages/skills-catalog/src/catalog-builder.ts

@@ -0,0 +1,443 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  asBoolean,
+  asString,
+  asStringArray,
+  parseFrontmatterMarkdown,
+} from "./frontmatter.js";
+import type {
+  CatalogManifest,
+  CatalogSkill,
+  CatalogSkillFile,
+  CatalogSkillFileKind,
+  CatalogSkillKind,
+  CatalogTrustLevel,
+} from "./types.js";
+
+const CATALOG_PACKAGE_NAME = "@paperclipai/skills-catalog";
+const CATALOG_SCHEMA_VERSION = 1;
+const SKILL_ENTRYPOINT = "SKILL.md";
+const MAX_CATALOG_FILE_BYTES = 1024 * 1024;
+const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const CATALOG_KINDS = new Set<CatalogSkillKind>(["bundled", "optional"]);
+
+interface SkillCandidate {
+  kind: CatalogSkillKind;
+  category: string;
+  slug: string;
+  absolutePath: string;
+}
+
+interface BuildCatalogManifestOptions {
+  packageDir: string;
+  generatedAt?: string;
+}
+
+interface BuildCatalogManifestResult {
+  manifest: CatalogManifest;
+  errors: string[];
+}
+
+export function formatCatalogManifest(manifest: CatalogManifest): string {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+export async function buildExpectedCatalogManifest(
+  packageDir: string,
+): Promise<BuildCatalogManifestResult> {
+  const existing = await readExistingManifest(packageDir);
+  const firstPass = await buildCatalogManifest({
+    packageDir,
+    generatedAt: existing?.generatedAt ?? new Date().toISOString(),
+  });
+
+  if (existing && sameManifestExceptGeneratedAt(existing, firstPass.manifest)) {
+    return firstPass;
+  }
+
+  return buildCatalogManifest({
+    packageDir,
+    generatedAt: new Date().toISOString(),
+  });
+}
+
+export async function buildCatalogManifest(
+  options: BuildCatalogManifestOptions,
+): Promise<BuildCatalogManifestResult> {
+  const packageDir = path.resolve(options.packageDir);
+  const packageJson = await readPackageJson(packageDir);
+  const errors: string[] = [];
+  const candidates = await discoverSkillCandidates(packageDir, errors);
+  const skills: CatalogSkill[] = [];
+
+  collectCandidateUniquenessErrors(candidates, errors);
+
+  for (const candidate of candidates) {
+    const skill = await buildCatalogSkill(packageDir, candidate, errors);
+    if (skill) skills.push(skill);
+  }
+
+  skills.sort((a, b) => a.id.localeCompare(b.id));
+  collectUniquenessErrors(skills, errors);
+
+  return {
+    manifest: {
+      schemaVersion: CATALOG_SCHEMA_VERSION,
+      packageName: CATALOG_PACKAGE_NAME,
+      packageVersion: packageJson.version,
+      generatedAt: options.generatedAt ?? new Date().toISOString(),
+      skills,
+    },
+    errors,
+  };
+}
+
+export async function validateCatalog(packageDir: string): Promise<BuildCatalogManifestResult> {
+  const expected = await buildExpectedCatalogManifest(packageDir);
+  const generatedPath = path.join(packageDir, "generated", "catalog.json");
+  const errors = [...expected.errors];
+
+  let generatedText: string | null = null;
+  try {
+    generatedText = await fs.readFile(generatedPath, "utf8");
+    JSON.parse(generatedText);
+  } catch (error) {
+    errors.push(`generated/catalog.json is missing or invalid: ${errorMessage(error)}`);
+  }
+
+  if (generatedText !== null) {
+    const expectedText = formatCatalogManifest(expected.manifest);
+    if (generatedText !== expectedText) {
+      errors.push("generated/catalog.json is stale. Run pnpm --filter @paperclipai/skills-catalog build:manifest.");
+    }
+  }
+
+  return {
+    manifest: expected.manifest,
+    errors,
+  };
+}
+
+export async function writeCatalogManifest(packageDir: string) {
+  const result = await buildExpectedCatalogManifest(packageDir);
+  if (result.errors.length > 0) return result;
+
+  const generatedDir = path.join(packageDir, "generated");
+  await fs.mkdir(generatedDir, { recursive: true });
+  await fs.writeFile(path.join(generatedDir, "catalog.json"), formatCatalogManifest(result.manifest), "utf8");
+  return result;
+}
+
+async function readPackageJson(packageDir: string) {
+  const packageJsonPath = path.join(packageDir, "package.json");
+  const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8")) as { version?: unknown };
+  const version = asString(packageJson.version);
+  if (!version) throw new Error(`${packageJsonPath} must declare a package version.`);
+  return { version };
+}
+
+async function readExistingManifest(packageDir: string): Promise<CatalogManifest | null> {
+  try {
+    return JSON.parse(await fs.readFile(path.join(packageDir, "generated", "catalog.json"), "utf8")) as CatalogManifest;
+  } catch {
+    return null;
+  }
+}
+
+async function discoverSkillCandidates(packageDir: string, errors: string[]) {
+  const catalogDir = path.join(packageDir, "catalog");
+  const candidates: SkillCandidate[] = [];
+
+  if (!existsSync(catalogDir)) {
+    errors.push("catalog directory is missing.");
+    return candidates;
+  }
+
+  await collectMisplacedSkillFiles(catalogDir, errors);
+
+  for (const kind of ["bundled", "optional"] as const) {
+    const kindDir = path.join(catalogDir, kind);
+    if (!existsSync(kindDir)) continue;
+
+    for (const categoryEntry of await sortedDirEntries(kindDir)) {
+      if (!categoryEntry.isDirectory()) continue;
+      const category = categoryEntry.name;
+      const categoryDir = path.join(kindDir, category);
+
+      for (const slugEntry of await sortedDirEntries(categoryDir)) {
+        if (!slugEntry.isDirectory()) continue;
+        const slug = slugEntry.name;
+        const skillDir = path.join(categoryDir, slug);
+        if (!existsSync(path.join(skillDir, SKILL_ENTRYPOINT))) {
+          errors.push(`${relativePackagePath(packageDir, skillDir)} is missing SKILL.md.`);
+          continue;
+        }
+        candidates.push({ kind, category, slug, absolutePath: skillDir });
+      }
+    }
+  }
+
+  return candidates;
+}
+
+async function collectMisplacedSkillFiles(catalogDir: string, errors: string[]) {
+  async function visit(dir: string) {
+    for (const entry of await sortedDirEntries(dir)) {
+      const absolutePath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await visit(absolutePath);
+        continue;
+      }
+      if (entry.name !== SKILL_ENTRYPOINT) continue;
+
+      const relativePath = toPosixPath(path.relative(catalogDir, absolutePath));
+      const parts = relativePath.split("/");
+      const kind = parts[0];
+      if (parts.length !== 4 || !CATALOG_KINDS.has(kind as CatalogSkillKind)) {
+        errors.push(`catalog/${relativePath} is not under catalog/<bundled|optional>/<category>/<slug>/SKILL.md.`);
+      }
+    }
+  }
+
+  await visit(catalogDir);
+}
+
+async function buildCatalogSkill(
+  packageDir: string,
+  candidate: SkillCandidate,
+  errors: string[],
+): Promise<CatalogSkill | null> {
+  const prefix = relativePackagePath(packageDir, candidate.absolutePath);
+  validateSlug("category", candidate.category, prefix, errors);
+  validateSlug("slug", candidate.slug, prefix, errors);
+
+  const id = `paperclipai:${candidate.kind}:${candidate.category}:${candidate.slug}`;
+  const key = `paperclipai/${candidate.kind}/${candidate.category}/${candidate.slug}`;
+  const skillMarkdownPath = path.join(candidate.absolutePath, SKILL_ENTRYPOINT);
+  const parsed = parseFrontmatterMarkdown(await fs.readFile(skillMarkdownPath, "utf8"));
+
+  if (!parsed.hasFrontmatter) {
+    errors.push(`${prefix}/SKILL.md must start with YAML frontmatter.`);
+  }
+
+  const name = asString(parsed.frontmatter.name);
+  if (!name) errors.push(`${prefix}/SKILL.md frontmatter must include name.`);
+
+  const description = asString(parsed.frontmatter.description);
+  if (!description) errors.push(`${prefix}/SKILL.md frontmatter must include description.`);
+
+  const explicitKey = asString(parsed.frontmatter.key);
+  if (explicitKey && explicitKey !== key) {
+    errors.push(`${prefix}/SKILL.md key must be ${key}.`);
+  }
+
+  const explicitSlug = asString(parsed.frontmatter.slug);
+  if (explicitSlug && explicitSlug !== candidate.slug) {
+    errors.push(`${prefix}/SKILL.md slug must be ${candidate.slug}.`);
+  }
+
+  const defaultInstall = asBoolean(parsed.frontmatter.defaultInstall) ?? false;
+  const recommendedForRoles = readStringArrayField(parsed.frontmatter.recommendedForRoles, "recommendedForRoles", prefix, errors);
+  const requires = readStringArrayField(parsed.frontmatter.requires, "requires", prefix, errors);
+  const tags = readStringArrayField(parsed.frontmatter.tags, "tags", prefix, errors);
+  const files = await collectSkillFiles(packageDir, candidate.absolutePath, prefix, errors);
+
+  if (!name || !description) return null;
+
+  return {
+    id,
+    key,
+    kind: candidate.kind,
+    category: candidate.category,
+    slug: candidate.slug,
+    name,
+    description,
+    path: toPosixPath(path.relative(packageDir, candidate.absolutePath)),
+    entrypoint: SKILL_ENTRYPOINT,
+    trustLevel: deriveTrustLevel(files),
+    compatibility: "compatible",
+    defaultInstall,
+    recommendedForRoles,
+    requires,
+    tags,
+    files,
+    contentHash: buildContentHash(files),
+  };
+}
+
+async function collectSkillFiles(
+  packageDir: string,
+  skillDir: string,
+  prefix: string,
+  errors: string[],
+): Promise<CatalogSkillFile[]> {
+  const files: CatalogSkillFile[] = [];
+  const skillRoot = await fs.realpath(skillDir);
+
+  async function visit(dir: string) {
+    for (const entry of await sortedDirEntries(dir)) {
+      const absolutePath = path.join(dir, entry.name);
+      const lstat = await fs.lstat(absolutePath);
+      let stat = lstat;
+      let realPath = absolutePath;
+
+      if (lstat.isSymbolicLink()) {
+        try {
+          realPath = await fs.realpath(absolutePath);
+          stat = await fs.stat(absolutePath);
+        } catch {
+          errors.push(`${relativePackagePath(packageDir, absolutePath)} is a broken symlink.`);
+          continue;
+        }
+        if (!isPathInside(skillRoot, realPath)) {
+          errors.push(`${relativePackagePath(packageDir, absolutePath)} points outside its skill directory.`);
+          continue;
+        }
+        if (stat.isDirectory()) {
+          errors.push(`${relativePackagePath(packageDir, absolutePath)} is a directory symlink; copy files into the skill directory instead.`);
+          continue;
+        }
+      }
+
+      if (stat.isDirectory()) {
+        await visit(absolutePath);
+        continue;
+      }
+      if (!stat.isFile()) continue;
+
+      const relativePath = toPosixPath(path.relative(skillDir, absolutePath));
+      if (path.isAbsolute(relativePath) || relativePath.split("/").includes("..")) {
+        errors.push(`${prefix}/${relativePath} has an invalid inventory path.`);
+        continue;
+      }
+      if (stat.size > MAX_CATALOG_FILE_BYTES) {
+        errors.push(`${prefix}/${relativePath} exceeds ${MAX_CATALOG_FILE_BYTES} bytes.`);
+      }
+
+      const contents = await fs.readFile(absolutePath);
+      files.push({
+        path: relativePath,
+        kind: classifyCatalogFile(relativePath),
+        sizeBytes: stat.size,
+        sha256: sha256(contents),
+      });
+    }
+  }
+
+  await visit(skillDir);
+  files.sort((a, b) => {
+    if (a.path === SKILL_ENTRYPOINT) return -1;
+    if (b.path === SKILL_ENTRYPOINT) return 1;
+    return a.path.localeCompare(b.path);
+  });
+
+  if (!files.some((file) => file.path === SKILL_ENTRYPOINT && file.kind === "skill")) {
+    errors.push(`${prefix} inventory does not contain SKILL.md.`);
+  }
+
+  return files;
+}
+
+function readStringArrayField(
+  value: unknown,
+  field: string,
+  prefix: string,
+  errors: string[],
+) {
+  const parsed = asStringArray(value);
+  if (!parsed) {
+    errors.push(`${prefix}/SKILL.md frontmatter field ${field} must be an array of strings.`);
+    return [];
+  }
+  return parsed;
+}
+
+function classifyCatalogFile(relativePath: string): CatalogSkillFileKind {
+  if (relativePath === SKILL_ENTRYPOINT) return "skill";
+  if (relativePath.startsWith("references/")) return "reference";
+  if (relativePath.startsWith("scripts/")) return "script";
+  if (relativePath.startsWith("assets/")) return "asset";
+  if (relativePath.endsWith(".md") || relativePath.endsWith(".mdx")) return "markdown";
+  return "other";
+}
+
+function deriveTrustLevel(files: CatalogSkillFile[]): CatalogTrustLevel {
+  if (files.some((file) => file.kind === "script")) return "scripts_executables";
+  if (files.some((file) => file.kind === "asset" || file.kind === "other")) return "assets";
+  return "markdown_only";
+}
+
+function buildContentHash(files: CatalogSkillFile[]) {
+  const hashInput = files.map((file) => ({
+    path: file.path,
+    sha256: file.sha256,
+  }));
+  return `sha256:${sha256(Buffer.from(JSON.stringify(hashInput)))}`;
+}
+
+function collectUniquenessErrors(skills: CatalogSkill[], errors: string[]) {
+  collectDuplicateErrors(skills, "id", errors);
+  collectDuplicateErrors(skills, "key", errors);
+  collectDuplicateErrors(skills, "slug", errors);
+}
+
+function collectCandidateUniquenessErrors(candidates: SkillCandidate[], errors: string[]) {
+  const projected = candidates.map((candidate) => ({
+    id: `paperclipai:${candidate.kind}:${candidate.category}:${candidate.slug}`,
+    key: `paperclipai/${candidate.kind}/${candidate.category}/${candidate.slug}`,
+    slug: candidate.slug,
+    path: toPosixPath(path.join("catalog", candidate.kind, candidate.category, candidate.slug)),
+  })) as CatalogSkill[];
+  collectUniquenessErrors(projected, errors);
+}
+
+function collectDuplicateErrors(fieldSkills: CatalogSkill[], field: "id" | "key" | "slug", errors: string[]) {
+  const seen = new Map<string, string>();
+  for (const skill of fieldSkills) {
+    const value = skill[field];
+    const first = seen.get(value);
+    if (first) {
+      errors.push(`Duplicate catalog ${field} "${value}" in ${first} and ${skill.path}.`);
+      continue;
+    }
+    seen.set(value, skill.path);
+  }
+}
+
+function validateSlug(label: string, value: string, prefix: string, errors: string[]) {
+  if (!SLUG_PATTERN.test(value)) {
+    errors.push(`${prefix} has invalid ${label} "${value}"; use lowercase URL slugs.`);
+  }
+}
+
+async function sortedDirEntries(dir: string) {
+  return (await fs.readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function sameManifestExceptGeneratedAt(a: CatalogManifest, b: CatalogManifest) {
+  return JSON.stringify({ ...a, generatedAt: "" }) === JSON.stringify({ ...b, generatedAt: "" });
+}
+
+function sha256(contents: Buffer) {
+  return createHash("sha256").update(contents).digest("hex");
+}
+
+function relativePackagePath(packageDir: string, absolutePath: string) {
+  return toPosixPath(path.relative(packageDir, absolutePath));
+}
+
+function toPosixPath(input: string) {
+  return input.split(path.sep).join("/");
+}
+
+function isPathInside(parent: string, child: string) {
+  const relativePath = path.relative(parent, child);
+  return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
+}
+
+function errorMessage(error: unknown) {
+  return error instanceof Error ? error.message : String(error);
+}

packages/skills-catalog/src/frontmatter.ts

@@ -0,0 +1,154 @@
+export interface MarkdownDoc {
+  frontmatter: Record<string, unknown>;
+  body: string;
+  hasFrontmatter: boolean;
+}
+
+export function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function asString(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+export function asBoolean(value: unknown): boolean | null {
+  return typeof value === "boolean" ? value : null;
+}
+
+export function asStringArray(value: unknown): string[] | null {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) return null;
+
+  const out: string[] = [];
+  for (const item of value) {
+    const text = asString(item);
+    if (!text) return null;
+    out.push(text);
+  }
+  return out;
+}
+
+export function parseFrontmatterMarkdown(raw: string): MarkdownDoc {
+  const normalized = raw.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    return { frontmatter: {}, body: normalized.trim(), hasFrontmatter: false };
+  }
+
+  const closing = normalized.indexOf("\n---\n", 4);
+  if (closing < 0) {
+    return { frontmatter: {}, body: normalized.trim(), hasFrontmatter: false };
+  }
+
+  const frontmatterRaw = normalized.slice(4, closing).trim();
+  const body = normalized.slice(closing + 5).trim();
+  return {
+    frontmatter: parseYamlFrontmatter(frontmatterRaw),
+    body,
+    hasFrontmatter: true,
+  };
+}
+
+function parseYamlFrontmatter(raw: string): Record<string, unknown> {
+  const prepared = prepareYamlLines(raw);
+  if (prepared.length === 0) return {};
+  const parsed = parseYamlBlock(prepared, 0, prepared[0]!.indent);
+  return isPlainRecord(parsed.value) ? parsed.value : {};
+}
+
+function prepareYamlLines(raw: string) {
+  return raw
+    .split("\n")
+    .map((line) => ({
+      indent: line.match(/^ */)?.[0].length ?? 0,
+      content: line.trim(),
+    }))
+    .filter((line) => line.content.length > 0 && !line.content.startsWith("#"));
+}
+
+function parseYamlBlock(
+  lines: Array<{ indent: number; content: string }>,
+  startIndex: number,
+  indentLevel: number,
+): { value: unknown; nextIndex: number } {
+  let index = startIndex;
+  if (index >= lines.length || lines[index]!.indent < indentLevel) {
+    return { value: {}, nextIndex: index };
+  }
+
+  const isArray = lines[index]!.indent === indentLevel && lines[index]!.content.startsWith("-");
+  if (isArray) {
+    const values: unknown[] = [];
+    while (index < lines.length) {
+      const line = lines[index]!;
+      if (line.indent < indentLevel) break;
+      if (line.indent !== indentLevel || !line.content.startsWith("-")) break;
+
+      const remainder = line.content.slice(1).trim();
+      index += 1;
+      if (!remainder) {
+        const nested = parseYamlBlock(lines, index, indentLevel + 2);
+        values.push(nested.value);
+        index = nested.nextIndex;
+        continue;
+      }
+
+      values.push(parseYamlScalar(remainder));
+    }
+    return { value: values, nextIndex: index };
+  }
+
+  const record: Record<string, unknown> = {};
+  while (index < lines.length) {
+    const line = lines[index]!;
+    if (line.indent < indentLevel) break;
+    if (line.indent !== indentLevel) {
+      index += 1;
+      continue;
+    }
+
+    const separatorIndex = line.content.indexOf(":");
+    if (separatorIndex <= 0) {
+      index += 1;
+      continue;
+    }
+
+    const key = line.content.slice(0, separatorIndex).trim();
+    const remainder = line.content.slice(separatorIndex + 1).trim();
+    index += 1;
+    if (!remainder) {
+      const nested = parseYamlBlock(lines, index, indentLevel + 2);
+      record[key] = nested.value;
+      index = nested.nextIndex;
+      continue;
+    }
+    record[key] = parseYamlScalar(remainder);
+  }
+
+  return { value: record, nextIndex: index };
+}
+
+function parseYamlScalar(rawValue: string): unknown {
+  const trimmed = rawValue.trim();
+  if (trimmed === "") return "";
+  if (trimmed === "null" || trimmed === "~") return null;
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed === "[]") return [];
+  if (trimmed === "{}") return {};
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed);
+  if (
+    trimmed.startsWith("\"") ||
+    trimmed.startsWith("[") ||
+    trimmed.startsWith("{")
+  ) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      return trimmed;
+    }
+  }
+  return trimmed;
+}

packages/skills-catalog/src/index.ts

@@ -0,0 +1,37 @@
+import catalogManifestJson from "../generated/catalog.json" with { type: "json" };
+import type { CatalogManifest, CatalogSkill } from "./types.js";
+
+export type {
+  CatalogCompatibility,
+  CatalogManifest,
+  CatalogSkill,
+  CatalogSkillFile,
+  CatalogSkillFileKind,
+  CatalogSkillKind,
+  CatalogTrustLevel,
+  CatalogValidationResult,
+} from "./types.js";
+
+export const catalogManifest = catalogManifestJson as CatalogManifest;
+
+export const catalogSkills: CatalogSkill[] = catalogManifest.skills;
+
+const skillsById = new Map(catalogSkills.map((skill) => [skill.id, skill]));
+const skillsByKey = new Map(catalogSkills.map((skill) => [skill.key, skill]));
+
+export function getCatalogSkill(id: string): CatalogSkill | null {
+  return skillsById.get(id) ?? null;
+}
+
+export function resolveCatalogSkillRef(ref: string): CatalogSkill | null {
+  const normalized = ref.trim();
+  if (normalized.length === 0) return null;
+
+  const exactMatch = skillsById.get(normalized) ?? skillsByKey.get(normalized);
+  if (exactMatch) return exactMatch;
+
+  const slugMatches = catalogSkills.filter((skill) => skill.slug === normalized);
+  if (slugMatches.length === 1) return slugMatches[0]!;
+
+  return null;
+}

packages/skills-catalog/src/shipped-catalog.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { catalogManifest, catalogSkills, resolveCatalogSkillRef } from "./index.js";
+import type { CatalogSkill } from "./types.js";
+
+const EXPECTED_BUNDLED_KEYS = [
+  "paperclipai/bundled/docs/doc-maintenance",
+  "paperclipai/bundled/paperclip-operations/issue-triage",
+  "paperclipai/bundled/paperclip-operations/task-planning",
+  "paperclipai/bundled/quality/qa-acceptance",
+  "paperclipai/bundled/software-development/github-pr-workflow",
+];
+
+const EXPECTED_OPTIONAL_KEYS = [
+  "paperclipai/optional/browser/agent-browser",
+  "paperclipai/optional/content/release-announcement",
+  "paperclipai/optional/product/design-critique",
+];
+
+describe("shipped skills catalog", () => {
+  it("ships the expected bundled and optional skill set", () => {
+    const bundledKeys = catalogSkills
+      .filter((skill) => skill.kind === "bundled")
+      .map((skill) => skill.key)
+      .sort();
+    const optionalKeys = catalogSkills
+      .filter((skill) => skill.kind === "optional")
+      .map((skill) => skill.key)
+      .sort();
+
+    expect(bundledKeys).toEqual(EXPECTED_BUNDLED_KEYS);
+    expect(optionalKeys).toEqual(EXPECTED_OPTIONAL_KEYS);
+  });
+
+  it("keeps every shipped skill markdown-only until a script-bearing skill clears security review", () => {
+    const scriptBearing = catalogSkills.filter((skill) => skill.trustLevel !== "markdown_only");
+    expect(scriptBearing, formatViolations("script-bearing skills require security review", scriptBearing)).toEqual([]);
+  });
+
+  it("populates browse/search-relevant fields for every shipped skill", () => {
+    const issues: string[] = [];
+    for (const skill of catalogSkills) {
+      if (skill.compatibility !== "compatible") {
+        issues.push(`${skill.key} compatibility=${skill.compatibility}`);
+      }
+      if (!skill.description || skill.description.length < 40) {
+        issues.push(`${skill.key} description must be at least 40 characters for catalog browse/search`);
+      }
+      if (skill.recommendedForRoles.length === 0) {
+        issues.push(`${skill.key} must list recommendedForRoles`);
+      }
+      if (skill.tags.length === 0) {
+        issues.push(`${skill.key} must list tags`);
+      }
+    }
+    expect(issues).toEqual([]);
+  });
+
+  it("uses canonical paperclipai keys derived from kind/category/slug", () => {
+    const violations: string[] = [];
+    for (const skill of catalogSkills) {
+      const expectedKey = `paperclipai/${skill.kind}/${skill.category}/${skill.slug}`;
+      const expectedId = `paperclipai:${skill.kind}:${skill.category}:${skill.slug}`;
+      if (skill.key !== expectedKey) violations.push(`${skill.key} should be ${expectedKey}`);
+      if (skill.id !== expectedId) violations.push(`${skill.id} should be ${expectedId}`);
+    }
+    expect(violations).toEqual([]);
+  });
+
+  it("exposes a stable manifest header for downstream consumers", () => {
+    expect(catalogManifest.schemaVersion).toBe(1);
+    expect(catalogManifest.packageName).toBe("@paperclipai/skills-catalog");
+    expect(catalogSkills.length).toBe(EXPECTED_BUNDLED_KEYS.length + EXPECTED_OPTIONAL_KEYS.length);
+  });
+
+  it("resolves shipped skills by id, key, and unique slug", () => {
+    const sample = catalogSkills.find((skill) => skill.key === "paperclipai/bundled/software-development/github-pr-workflow");
+    expect(sample, "expected github-pr-workflow to ship in the bundled catalog").toBeDefined();
+    if (!sample) return;
+
+    expect(resolveCatalogSkillRef(sample.id)).toMatchObject({ key: sample.key });
+    expect(resolveCatalogSkillRef(sample.key)).toMatchObject({ key: sample.key });
+    expect(resolveCatalogSkillRef(sample.slug)).toMatchObject({ key: sample.key });
+  });
+});
+
+function formatViolations(label: string, skills: CatalogSkill[]) {
+  if (skills.length === 0) return label;
+  const detail = skills.map((skill) => `${skill.key} (${skill.trustLevel})`).join(", ");
+  return `${label}: ${detail}`;
+}

packages/skills-catalog/src/types.ts

@@ -0,0 +1,48 @@
+export type CatalogSkillKind = "bundled" | "optional";
+
+export type CatalogTrustLevel = "markdown_only" | "assets" | "scripts_executables";
+
+export type CatalogCompatibility = "compatible" | "unknown" | "invalid";
+
+export type CatalogSkillFileKind = "skill" | "markdown" | "reference" | "script" | "asset" | "other";
+
+export interface CatalogSkillFile {
+  path: string;
+  kind: CatalogSkillFileKind;
+  sizeBytes: number;
+  sha256: string;
+}
+
+export interface CatalogSkill {
+  id: string;
+  key: string;
+  kind: CatalogSkillKind;
+  category: string;
+  slug: string;
+  name: string;
+  description: string;
+  path: string;
+  entrypoint: "SKILL.md";
+  trustLevel: CatalogTrustLevel;
+  compatibility: CatalogCompatibility;
+  defaultInstall: boolean;
+  recommendedForRoles: string[];
+  requires: string[];
+  tags: string[];
+  files: CatalogSkillFile[];
+  contentHash: string;
+}
+
+export interface CatalogManifest {
+  schemaVersion: 1;
+  packageName: "@paperclipai/skills-catalog";
+  packageVersion: string;
+  generatedAt: string;
+  skills: CatalogSkill[];
+}
+
+export interface CatalogValidationResult {
+  valid: boolean;
+  errors: string[];
+  manifest: CatalogManifest;
+}

packages/skills-catalog/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "."
+  },
+  "include": ["generated/**/*.json", "scripts/**/*.ts", "src/**/*.ts"]
+}

packages/skills-catalog/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+  },
+});