[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>
This commit is contained in:
Dotta 2026-05-28 07:33:51 -10:00 committed by GitHub
parent 8da50dbcf8
commit 9eac727cf1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
77 changed files with 9704 additions and 530 deletions

View file

@ -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,

View file

@ -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[];
}

View file

@ -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,

View file

@ -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 });
});
});

View file

@ -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>;

View file

@ -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,