@vellumai/plugin-api 0.10.7-dev.202607091922.eeb94f9 → 0.10.7-dev.202607092039.003f549

package/index.d.ts

@@ -3470,6 +3470,30 @@ declare type InterfaceId = (typeof INTERFACE_IDS)[number];
  */
 export declare function isMaxTokensStopReason(stopReason: string | null | undefined): boolean;
 
+/**
+ * The remote skill catalog, fetched via the shared catalog cache. Entries
+ * whose declared feature flag is disabled are reported with
+ * `state: "unavailable"`; all others are `state: "available"`. Not deduplicated
+ * against the installed catalog — callers that merge the two lists filter by
+ * installed ids themselves.
+ *
+ * A fetch failure never rejects: the underlying cache degrades through its
+ * fallback chain (stale cache → bundled local catalog → empty) and this
+ * returns whatever that yields. An empty result therefore means "could not
+ * enumerate the catalog" as much as "the catalog is empty" — callers must
+ * gate destructive reconciliation (pruning against the catalog id set) on a
+ * non-empty result. Unexpected errors from the catalog read propagate.
+ */
+export declare function listCatalogSkills(): Promise<ResolvedSkillEntry[]>;
+
+/**
+ * The locally installed skill catalog with resolved states. Includes every
+ * catalog entry — skills dropped by flag gating or the bundled allowlist are
+ * reported with `state: "unavailable"` rather than omitted, so the returned
+ * ids are the complete installed universe.
+ */
+export declare function listInstalledSkills(): Promise<ResolvedSkillEntry[]>;
+
 declare interface ListItem {
     id: string;
     title: string;
@@ -4468,6 +4492,52 @@ declare const RelationshipStateUpdatedEventSchema: z.ZodObject<{
     updatedAt: z.ZodString;
 }, z.core.$strip>;
 
+/**
+ * Plugin-facing read API over the skill surface: the locally installed
+ * catalog with resolved enablement states, and the remote skill catalog —
+ * each composed host-side (catalog load + install-state resolution +
+ * feature-flag gating + install-meta read), so callers hold no host config
+ * and perform no flag checks of their own.
+ *
+ * The underlying skill and flag modules are loaded via dynamic `import()`
+ * inside each function so that importing this module — which every
+ * `@vellumai/plugin-api` consumer does transitively — does not eagerly pull
+ * the catalog/flag import graph. An eager pull would force those modules'
+ * named exports to resolve at instantiation, which breaks the intentional
+ * partial module mocks in tests.
+ */
+/** One skill as seen by a plugin: capability fields plus resolved state. */
+export declare interface ResolvedSkillEntry {
+    id: string;
+    displayName: string;
+    description: string;
+    /** Compact routing cues declared in frontmatter / catalog metadata. */
+    activationHints?: string[];
+    /** Conditions under which the skill should not be loaded. */
+    avoidWhen?: string[];
+    /** True when the skill is pinned into the memory selector pool every turn. */
+    alwaysCandidate?: boolean;
+    /** True for locally installed skills; false for remote catalog entries. */
+    installed: boolean;
+    /** Where the installed skill comes from. Unset for remote catalog entries. */
+    source?: SkillSource;
+    /**
+     * Resolved availability:
+     * - `enabled` / `disabled` — installed, per config and source defaults.
+     * - `unavailable` — gated off (feature flag disabled, or a bundled skill
+     *   excluded by the `allowBundled` allowlist). Present so callers can still
+     *   enumerate the full id universe.
+     * - `available` — a remote catalog entry that is not locally installed.
+     */
+    state: "enabled" | "disabled" | "unavailable" | "available";
+    /**
+     * Install metadata for user-installed skills (`managed` / `workspace` /
+     * `extra` sources): `null` when the directory has no install-meta file,
+     * unset for sources that never carry one (bundled, plugin, remote).
+     */
+    installMeta?: SkillInstallMeta | null;
+}
+
 /**
  * Resolve a media source to inline base64, reading a reference source back from
  * its workspace location. Returns `null` when a reference can no longer be
@@ -4829,6 +4899,21 @@ declare interface SkillBodyResponse {
     error?: string;
 }
 
+declare interface SkillInstallMeta {
+    origin: "vellum" | "clawhub" | "skillssh" | "custom";
+    installedAt: string;
+    installedBy?: string;
+    backfilledBy?: string;
+    version?: string;
+    slug?: string;
+    sourceRepo?: string;
+    contentHash?: string;
+    author?: "assistant" | "user";
+    sourceConversationId?: string;
+    retrospectiveConversationId?: string;
+    lastUsedAt?: string;
+}
+
 declare interface SkillsDraftResponse {
     type: "skills_draft_response";
     success: boolean;
@@ -4884,6 +4969,20 @@ declare interface SkillsListResponse {
     skills: SlimSkillResponse[];
 }
 
+/**
+ * Origin of a skill in the merged catalog.
+ *
+ * - `bundled`: ships inside the assistant binary under `bundled-skills/`.
+ * - `managed`: installed into `$VELLUM_WORKSPACE_DIR/skills/` from our catalog.
+ * - `workspace`: user-authored skill living in a conversation's working dir.
+ * - `extra`: third-party directory roots passed via `loadSkillCatalog`'s
+ *   `extraDirs` argument (primarily for tests).
+ * - `plugin`: shipped on disk inside an installed plugin at
+ *   `<workspaceDir>/plugins/<name>/skills/<id>/SKILL.md`, attributed back to
+ *   the owning plugin via its `owner` descriptor.
+ */
+declare type SkillSource = "bundled" | "managed" | "workspace" | "extra" | "plugin";
+
 declare type _SkillsServerMessages = SkillsListResponse | SkillBodyResponse | SkillStateChanged | SkillsInspectResponse | SkillsDraftResponse;
 
 declare interface SkillsshSlimSkill extends SlimSkillBase {

package/index.js

@@ -9,6 +9,8 @@ export const getAssistantName = api.getAssistantName;
 export const getConfiguredProvider = api.getConfiguredProvider;
 export const getModelProfiles = api.getModelProfiles;
 export const isMaxTokensStopReason = api.isMaxTokensStopReason;
+export const listCatalogSkills = api.listCatalogSkills;
+export const listInstalledSkills = api.listInstalledSkills;
 export const resolveMediaSourceData = api.resolveMediaSourceData;
 export const resolveUserName = api.resolveUserName;
 export const selectedBackendSupportsMultimodal = api.selectedBackendSupportsMultimodal;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.10.7-dev.202607091922.eeb94f9",
+  "version": "0.10.7-dev.202607092039.003f549",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",