Implement skills store API foundation

Co-Authored-By: Paperclip <noreply@paperclip.ing>

packages/shared/src/index.ts

@@ -334,11 +334,23 @@ export type {
   CompanySkillTrustLevel,
   CompanySkillCompatibility,
   CompanySkillSourceBadge,
+  CompanySkillSharingScope,
+  CompanySkillListSort,
   CompanySkillFileInventoryEntry,
+  CompanySkillVersionFileInventoryEntry,
   CompanySkill,
   CompanySkillListItem,
   CompanySkillUsageAgent,
   CompanySkillDetail,
+  CompanySkillListQuery,
+  CompanySkillCategoryCount,
+  CompanySkillVersion,
+  CompanySkillVersionCreateRequest,
+  CompanySkillStarResult,
+  CompanySkillComment,
+  CompanySkillCommentCreateRequest,
+  CompanySkillCommentUpdateRequest,
+  CompanySkillForkRequest,
   CompanySkillUpdateStatus,
   CompanySkillAuditSeverity,
   CompanySkillAuditVerdict,
@@ -390,6 +402,7 @@ export type {
   AgentSkillSyncMode,
   AgentSkillState,
   AgentSkillOrigin,
+  AgentDesiredSkillEntry,
   AgentSkillEntry,
   AgentSkillSnapshot,
   AgentSkillSyncRequest,
@@ -918,6 +931,8 @@ export {
   type ProbeEnvironmentConfig,
   agentSkillStateSchema,
   agentSkillSyncModeSchema,
+  agentDesiredSkillEntrySchema,
+  agentDesiredSkillSelectionSchema,
   agentSkillEntrySchema,
   agentSkillSnapshotSchema,
   agentSkillSyncSchema,
@@ -1212,11 +1227,23 @@ export {
   companySkillTrustLevelSchema,
   companySkillCompatibilitySchema,
   companySkillSourceBadgeSchema,
+  companySkillSharingScopeSchema,
+  companySkillListSortSchema,
   companySkillFileInventoryEntrySchema,
+  companySkillVersionFileInventoryEntrySchema,
   companySkillSchema,
   companySkillListItemSchema,
   companySkillUsageAgentSchema,
+  companySkillListQuerySchema,
+  companySkillCategoryCountSchema,
+  companySkillVersionSchema,
   companySkillDetailSchema,
+  companySkillVersionCreateSchema,
+  companySkillStarResultSchema,
+  companySkillCommentSchema,
+  companySkillCommentCreateSchema,
+  companySkillCommentUpdateSchema,
+  companySkillForkSchema,
   companySkillUpdateStatusSchema,
   companySkillAuditFindingSchema,
   companySkillAuditResultSchema,

packages/shared/src/types/adapter-skills.ts

@@ -14,9 +14,16 @@ export type AgentSkillOrigin =
   | "user_installed"
   | "external_unknown";
 
+export interface AgentDesiredSkillEntry {
+  key: string;
+  versionId: string | null;
+}
+
 export interface AgentSkillEntry {
   key: string;
   runtimeName: string | null;
+  versionId?: string | null;
+  currentVersionId?: string | null;
   desired: boolean;
   managed: boolean;
   required?: boolean;
@@ -36,10 +43,11 @@ export interface AgentSkillSnapshot {
   supported: boolean;
   mode: AgentSkillSyncMode;
   desiredSkills: string[];
+  desiredSkillEntries?: AgentDesiredSkillEntry[];
   entries: AgentSkillEntry[];
   warnings: string[];
 }
 
 export interface AgentSkillSyncRequest {
-  desiredSkills: string[];
+  desiredSkills: Array<string | AgentDesiredSkillEntry>;
 }

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

@@ -6,11 +6,19 @@ export type CompanySkillCompatibility = "compatible" | "unknown" | "invalid";
 
 export type CompanySkillSourceBadge = "paperclip" | "github" | "local" | "url" | "catalog" | "skills_sh";
 
+export type CompanySkillSharingScope = "private" | "company" | "public_link";
+
+export type CompanySkillListSort = "alphabetical" | "recent" | "installs" | "stars" | "agents" | "forks";
+
 export interface CompanySkillFileInventoryEntry {
   path: string;
   kind: "skill" | "markdown" | "reference" | "script" | "asset" | "other";
 }
 
+export interface CompanySkillVersionFileInventoryEntry extends CompanySkillFileInventoryEntry {
+  content: string;
+}
+
 export interface CompanySkill {
   id: string;
   companyId: string;
@@ -25,6 +33,20 @@ export interface CompanySkill {
   trustLevel: CompanySkillTrustLevel;
   compatibility: CompanySkillCompatibility;
   fileInventory: CompanySkillFileInventoryEntry[];
+  iconUrl: string | null;
+  color: string | null;
+  tagline: string | null;
+  authorName: string | null;
+  homepageUrl: string | null;
+  categories: string[];
+  sharingScope: CompanySkillSharingScope;
+  publicShareToken: string | null;
+  forkedFromSkillId: string | null;
+  forkedFromCompanyId: string | null;
+  starCount: number;
+  installCount: number;
+  forkCount: number;
+  currentVersionId: string | null;
   metadata: Record<string, unknown> | null;
   createdAt: Date;
   updatedAt: Date;
@@ -43,6 +65,20 @@ export interface CompanySkillListItem {
   trustLevel: CompanySkillTrustLevel;
   compatibility: CompanySkillCompatibility;
   fileInventory: CompanySkillFileInventoryEntry[];
+  iconUrl: string | null;
+  color: string | null;
+  tagline: string | null;
+  authorName: string | null;
+  homepageUrl: string | null;
+  categories: string[];
+  sharingScope: CompanySkillSharingScope;
+  publicShareToken: string | null;
+  forkedFromSkillId: string | null;
+  forkedFromCompanyId: string | null;
+  starCount: number;
+  installCount: number;
+  forkCount: number;
+  currentVersionId: string | null;
   createdAt: Date;
   updatedAt: Date;
   attachedAgentCount: number;
@@ -69,6 +105,7 @@ export interface CompanySkillUsageAgent {
    * agent runtimes while loading operator-facing skill metadata.
    */
   actualState: string | null;
+  versionId: string | null;
 }
 
 export interface CompanySkillDetail extends CompanySkill {
@@ -79,6 +116,70 @@ export interface CompanySkillDetail extends CompanySkill {
   sourceLabel: string | null;
   sourceBadge: CompanySkillSourceBadge;
   sourcePath: string | null;
+  currentVersion: CompanySkillVersion | null;
+  starredByCurrentActor: boolean;
+}
+
+export interface CompanySkillListQuery {
+  q?: string;
+  sort?: CompanySkillListSort;
+  categories?: string[];
+  scope?: CompanySkillSharingScope;
+}
+
+export interface CompanySkillCategoryCount {
+  slug: string;
+  count: number;
+}
+
+export interface CompanySkillVersion {
+  id: string;
+  companyId: string;
+  companySkillId: string;
+  revisionNumber: number;
+  label: string | null;
+  fileInventory: CompanySkillVersionFileInventoryEntry[];
+  authorAgentId: string | null;
+  authorUserId: string | null;
+  createdAt: Date;
+}
+
+export interface CompanySkillVersionCreateRequest {
+  label?: string | null;
+}
+
+export interface CompanySkillStarResult {
+  skillId: string;
+  starred: boolean;
+  starCount: number;
+}
+
+export interface CompanySkillComment {
+  id: string;
+  companyId: string;
+  companySkillId: string;
+  parentCommentId: string | null;
+  authorAgentId: string | null;
+  authorUserId: string | null;
+  body: string;
+  deletedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface CompanySkillCommentCreateRequest {
+  body: string;
+  parentCommentId?: string | null;
+}
+
+export interface CompanySkillCommentUpdateRequest {
+  body: string;
+}
+
+export interface CompanySkillForkRequest {
+  name?: string | null;
+  slug?: string | null;
+  sharingScope?: CompanySkillSharingScope;
 }
 
 export interface CompanySkillUpdateStatus {
@@ -186,6 +287,13 @@ export interface CompanySkillCreateRequest {
   slug?: string | null;
   description?: string | null;
   markdown?: string | null;
+  iconUrl?: string | null;
+  color?: string | null;
+  tagline?: string | null;
+  authorName?: string | null;
+  homepageUrl?: string | null;
+  categories?: string[];
+  sharingScope?: CompanySkillSharingScope;
 }
 
 export interface CompanySkillFileDetail {

packages/shared/src/types/index.ts

@@ -60,11 +60,23 @@ export type {
   CompanySkillTrustLevel,
   CompanySkillCompatibility,
   CompanySkillSourceBadge,
+  CompanySkillSharingScope,
+  CompanySkillListSort,
   CompanySkillFileInventoryEntry,
+  CompanySkillVersionFileInventoryEntry,
   CompanySkill,
   CompanySkillListItem,
   CompanySkillUsageAgent,
   CompanySkillDetail,
+  CompanySkillListQuery,
+  CompanySkillCategoryCount,
+  CompanySkillVersion,
+  CompanySkillVersionCreateRequest,
+  CompanySkillStarResult,
+  CompanySkillComment,
+  CompanySkillCommentCreateRequest,
+  CompanySkillCommentUpdateRequest,
+  CompanySkillForkRequest,
   CompanySkillUpdateStatus,
   CompanySkillAuditSeverity,
   CompanySkillAuditVerdict,
@@ -120,6 +132,7 @@ export type {
   AgentSkillSyncMode,
   AgentSkillState,
   AgentSkillOrigin,
+  AgentDesiredSkillEntry,
   AgentSkillEntry,
   AgentSkillSnapshot,
   AgentSkillSyncRequest,

packages/shared/src/validators/adapter-skills.ts

@@ -22,9 +22,21 @@ export const agentSkillSyncModeSchema = z.enum([
   "ephemeral",
 ]);
 
+export const agentDesiredSkillEntrySchema = z.object({
+  key: z.string().min(1),
+  versionId: z.string().uuid().nullable(),
+});
+
+export const agentDesiredSkillSelectionSchema = z.union([
+  z.string().min(1),
+  agentDesiredSkillEntrySchema,
+]);
+
 export const agentSkillEntrySchema = z.object({
   key: z.string().min(1),
   runtimeName: z.string().min(1).nullable(),
+  versionId: z.string().uuid().nullable().optional(),
+  currentVersionId: z.string().uuid().nullable().optional(),
   desired: z.boolean(),
   managed: z.boolean(),
   required: z.boolean().optional(),
@@ -44,12 +56,13 @@ export const agentSkillSnapshotSchema = z.object({
   supported: z.boolean(),
   mode: agentSkillSyncModeSchema,
   desiredSkills: z.array(z.string().min(1)),
+  desiredSkillEntries: z.array(agentDesiredSkillEntrySchema).optional(),
   entries: z.array(agentSkillEntrySchema),
   warnings: z.array(z.string()),
 });
 
 export const agentSkillSyncSchema = z.object({
-  desiredSkills: z.array(z.string().min(1)),
+  desiredSkills: z.array(agentDesiredSkillSelectionSchema),
 });
 
 export type AgentSkillSync = z.infer<typeof agentSkillSyncSchema>;

packages/shared/src/validators/agent.ts

@@ -8,6 +8,7 @@ import {
 import { agentAdapterTypeSchema } from "../adapter-type.js";
 import { envConfigSchema } from "./secret.js";
 import { trustAuthorizationPolicySchema, trustPresetSchema } from "./trust-policy.js";
+import { agentDesiredSkillSelectionSchema } from "./adapter-skills.js";
 
 export const agentPermissionsSchema = z.object({
   canCreateAgents: z.boolean().optional().default(false),
@@ -73,7 +74,7 @@ export const createAgentSchema = z.object({
   icon: z.enum(AGENT_ICON_NAMES).optional().nullable(),
   reportsTo: z.string().uuid().optional().nullable(),
   capabilities: z.string().optional().nullable(),
-  desiredSkills: z.array(z.string().min(1)).optional(),
+  desiredSkills: z.array(agentDesiredSkillSelectionSchema).optional(),
   adapterType: agentAdapterTypeSchema,
   adapterConfig: adapterConfigSchema.optional().default({}),
   instructionsBundle: createAgentInstructionsBundleSchema.optional(),

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

@@ -4,12 +4,18 @@ export const companySkillSourceTypeSchema = z.enum(["local_path", "github", "url
 export const companySkillTrustLevelSchema = z.enum(["markdown_only", "assets", "scripts_executables"]);
 export const companySkillCompatibilitySchema = z.enum(["compatible", "unknown", "invalid"]);
 export const companySkillSourceBadgeSchema = z.enum(["paperclip", "github", "local", "url", "catalog", "skills_sh"]);
+export const companySkillSharingScopeSchema = z.enum(["private", "company", "public_link"]);
+export const companySkillListSortSchema = z.enum(["alphabetical", "recent", "installs", "stars", "agents", "forks"]);
 
 export const companySkillFileInventoryEntrySchema = z.object({
   path: z.string().min(1),
   kind: z.enum(["skill", "markdown", "reference", "script", "asset", "other"]),
 });
 
+export const companySkillVersionFileInventoryEntrySchema = companySkillFileInventoryEntrySchema.extend({
+  content: z.string(),
+});
+
 export const companySkillSchema = z.object({
   id: z.string().uuid(),
   companyId: z.string().uuid(),
@@ -24,6 +30,20 @@ export const companySkillSchema = z.object({
   trustLevel: companySkillTrustLevelSchema,
   compatibility: companySkillCompatibilitySchema,
   fileInventory: z.array(companySkillFileInventoryEntrySchema).default([]),
+  iconUrl: z.string().nullable(),
+  color: z.string().nullable(),
+  tagline: z.string().nullable(),
+  authorName: z.string().nullable(),
+  homepageUrl: z.string().nullable(),
+  categories: z.array(z.string().min(1)).default([]),
+  sharingScope: companySkillSharingScopeSchema,
+  publicShareToken: z.string().nullable(),
+  forkedFromSkillId: z.string().uuid().nullable(),
+  forkedFromCompanyId: z.string().uuid().nullable(),
+  starCount: z.number().int().nonnegative(),
+  installCount: z.number().int().nonnegative(),
+  forkCount: z.number().int().nonnegative(),
+  currentVersionId: z.string().uuid().nullable(),
   metadata: z.record(z.string(), z.unknown()).nullable(),
   createdAt: z.coerce.date(),
   updatedAt: z.coerce.date(),
@@ -50,6 +70,31 @@ export const companySkillUsageAgentSchema = z.object({
   actualState: z.string().nullable().describe(
     "Runtime adapter skill state when explicitly fetched; company skill detail reads return null without probing agent runtimes.",
   ),
+  versionId: z.string().uuid().nullable(),
+});
+
+export const companySkillListQuerySchema = z.object({
+  q: z.string().min(1).optional(),
+  sort: companySkillListSortSchema.optional(),
+  categories: z.array(z.string().min(1)).optional(),
+  scope: companySkillSharingScopeSchema.optional(),
+});
+
+export const companySkillCategoryCountSchema = z.object({
+  slug: z.string().min(1),
+  count: z.number().int().nonnegative(),
+});
+
+export const companySkillVersionSchema = z.object({
+  id: z.string().uuid(),
+  companyId: z.string().uuid(),
+  companySkillId: z.string().uuid(),
+  revisionNumber: z.number().int().positive(),
+  label: z.string().nullable(),
+  fileInventory: z.array(companySkillVersionFileInventoryEntrySchema).default([]),
+  authorAgentId: z.string().uuid().nullable(),
+  authorUserId: z.string().nullable(),
+  createdAt: z.coerce.date(),
 });
 
 export const companySkillDetailSchema = companySkillSchema.extend({
@@ -59,8 +104,48 @@ export const companySkillDetailSchema = companySkillSchema.extend({
   editableReason: z.string().nullable(),
   sourceLabel: z.string().nullable(),
   sourceBadge: companySkillSourceBadgeSchema,
+  currentVersion: companySkillVersionSchema.nullable(),
+  starredByCurrentActor: z.boolean(),
 });
 
+export const companySkillVersionCreateSchema = z.object({
+  label: z.string().trim().min(1).nullable().optional(),
+}).default({});
+
+export const companySkillStarResultSchema = z.object({
+  skillId: z.string().uuid(),
+  starred: z.boolean(),
+  starCount: z.number().int().nonnegative(),
+});
+
+export const companySkillCommentSchema = z.object({
+  id: z.string().uuid(),
+  companyId: z.string().uuid(),
+  companySkillId: z.string().uuid(),
+  parentCommentId: z.string().uuid().nullable(),
+  authorAgentId: z.string().uuid().nullable(),
+  authorUserId: z.string().nullable(),
+  body: z.string(),
+  deletedAt: z.coerce.date().nullable(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+});
+
+export const companySkillCommentCreateSchema = z.object({
+  body: z.string().min(1),
+  parentCommentId: z.string().uuid().nullable().optional(),
+});
+
+export const companySkillCommentUpdateSchema = z.object({
+  body: z.string().min(1),
+});
+
+export const companySkillForkSchema = z.object({
+  name: z.string().min(1).nullable().optional(),
+  slug: z.string().min(1).nullable().optional(),
+  sharingScope: companySkillSharingScopeSchema.optional(),
+}).default({});
+
 export const companySkillUpdateStatusSchema = z.object({
   supported: z.boolean(),
   reason: z.string().nullable(),
@@ -156,6 +241,13 @@ export const companySkillCreateSchema = z.object({
   slug: z.string().min(1).nullable().optional(),
   description: z.string().nullable().optional(),
   markdown: z.string().nullable().optional(),
+  iconUrl: z.string().nullable().optional(),
+  color: z.string().nullable().optional(),
+  tagline: z.string().max(120).nullable().optional(),
+  authorName: z.string().nullable().optional(),
+  homepageUrl: z.string().nullable().optional(),
+  categories: z.array(z.string().min(1)).optional(),
+  sharingScope: companySkillSharingScopeSchema.optional(),
 });
 
 export const companySkillFileDetailSchema = z.object({
@@ -247,9 +339,14 @@ export const companySkillInstallCatalogResultSchema = z.object({
 });
 
 export type CompanySkillImport = z.infer<typeof companySkillImportSchema>;
+export type CompanySkillListQuery = z.infer<typeof companySkillListQuerySchema>;
 export type CompanySkillProjectScan = z.infer<typeof companySkillProjectScanRequestSchema>;
 export type CompanySkillCreate = z.infer<typeof companySkillCreateSchema>;
 export type CompanySkillFileUpdate = z.infer<typeof companySkillFileUpdateSchema>;
+export type CompanySkillVersionCreate = z.infer<typeof companySkillVersionCreateSchema>;
+export type CompanySkillCommentCreate = z.infer<typeof companySkillCommentCreateSchema>;
+export type CompanySkillCommentUpdate = z.infer<typeof companySkillCommentUpdateSchema>;
+export type CompanySkillFork = z.infer<typeof companySkillForkSchema>;
 export type CatalogSkillListQuery = z.infer<typeof catalogSkillListQuerySchema>;
 export type CompanySkillInstallCatalog = z.infer<typeof companySkillInstallCatalogSchema>;
 export type CompanySkillInstallUpdate = z.infer<typeof companySkillInstallUpdateSchema>;

packages/shared/src/validators/index.ts

@@ -61,11 +61,23 @@ export {
   companySkillTrustLevelSchema,
   companySkillCompatibilitySchema,
   companySkillSourceBadgeSchema,
+  companySkillSharingScopeSchema,
+  companySkillListSortSchema,
   companySkillFileInventoryEntrySchema,
+  companySkillVersionFileInventoryEntrySchema,
   companySkillSchema,
   companySkillListItemSchema,
   companySkillUsageAgentSchema,
+  companySkillListQuerySchema,
+  companySkillCategoryCountSchema,
+  companySkillVersionSchema,
   companySkillDetailSchema,
+  companySkillVersionCreateSchema,
+  companySkillStarResultSchema,
+  companySkillCommentSchema,
+  companySkillCommentCreateSchema,
+  companySkillCommentUpdateSchema,
+  companySkillForkSchema,
   companySkillUpdateStatusSchema,
   companySkillAuditFindingSchema,
   companySkillAuditResultSchema,
@@ -89,9 +101,14 @@ export {
   companySkillInstallUpdateSchema,
   companySkillResetSchema,
   type CompanySkillImport,
+  type CompanySkillListQuery,
   type CompanySkillProjectScan,
   type CompanySkillCreate,
   type CompanySkillFileUpdate,
+  type CompanySkillVersionCreate,
+  type CompanySkillCommentCreate,
+  type CompanySkillCommentUpdate,
+  type CompanySkillFork,
   type CatalogSkillListQuery,
   type CompanySkillInstallCatalog,
   type CompanySkillInstallUpdate,
@@ -121,6 +138,8 @@ export {
 export {
   agentSkillStateSchema,
   agentSkillSyncModeSchema,
+  agentDesiredSkillEntrySchema,
+  agentDesiredSkillSelectionSchema,
   agentSkillEntrySchema,
   agentSkillSnapshotSchema,
   agentSkillSyncSchema,