@databricks/appkit 0.66.1 → 0.68.0

package/docs/api/appkit/Function.defineSchema.md

@@ -1,17 +1,25 @@
 # Function: defineSchema()
 
 ```ts
-function defineSchema(builder: (context: SchemaBuilderContext) => Record<string, AppKitTable>, options?: DefineSchemaOptions): Schema;
+function defineSchema<TTables>(builder: (context: SchemaBuilderContext) => TTables, options?: DefineSchemaOptions): Schema<Extract<keyof TTables, string>>;
 
 ```
 
+Compile one declared schema. The returned type keeps the table names the builder returned, so `crudRoutes` and `hooks` can name only real tables.
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter                                        |
+| ----------------------------------------------------- |
+| `TTables` *extends* `Record`<`string`, `AppKitTable`> |
+
 ## Parameters[​](#parameters "Direct link to Parameters")
 
-| Parameter  | Type                                                                     |
-| ---------- | ------------------------------------------------------------------------ |
-| `builder`  | (`context`: `SchemaBuilderContext`) => `Record`<`string`, `AppKitTable`> |
-| `options?` | `DefineSchemaOptions`                                                    |
+| Parameter  | Type                                             |
+| ---------- | ------------------------------------------------ |
+| `builder`  | (`context`: `SchemaBuilderContext`) => `TTables` |
+| `options?` | `DefineSchemaOptions`                            |
 
 ## Returns[​](#returns "Direct link to Returns")
 
-[`Schema`](./docs/api/appkit/Interface.Schema.md)
+[`Schema`](./docs/api/appkit/Interface.Schema.md)<`Extract`\<keyof `TTables`, `string`>>

package/docs/api/appkit/Interface.AgentDefinition.md

@@ -118,6 +118,17 @@ Setting `name` to a value that differs from the registry key is harmless but con
 
 ***
 
+### skills?[​](#skills "Direct link to skills?")
+
+```ts
+optional skills: string[];
+
+```
+
+Names of global skills (shared `skills/` pool or catalog volume) to make visible to this agent. Per-agent skills under `<id>/skills/` are always visible and need not be listed. Ignored when the plugin's `autoInheritSkills` makes every global skill visible.
+
+***
+
 ### tools?[​](#tools "Direct link to tools?")
 
 ```ts

package/docs/api/appkit/Interface.AgentsPluginConfig.md

@@ -60,6 +60,19 @@ Milliseconds to wait before auto-denying. Default: 60\_000.
 
 ***
 
+### autoInheritSkills?[​](#autoinheritskills "Direct link to autoInheritSkills?")
+
+```ts
+optional autoInheritSkills: 
+  | boolean
+  | AutoInheritToolsConfig;
+
+```
+
+Whether every global skill (shared `skills/` pool or catalog volume) is visible to an agent without listing it in `skills:` frontmatter. Off by default so each agent's always-on skill catalog stays lean; accepts a boolean shorthand or a per-origin `{ file, code }` config, mirroring [autoInheritTools](#autoinherittools).
+
+***
+
 ### autoInheritTools?[​](#autoinherittools "Direct link to autoInheritTools?")
 
 ```ts
@@ -198,6 +211,28 @@ optional name: string;
 
 ***
 
+### skillCredentialMode?[​](#skillcredentialmode "Direct link to skillCredentialMode?")
+
+```ts
+optional skillCredentialMode: "sp" | "obo";
+
+```
+
+Identity used to read catalog (volume) skills. v1 supports `"sp"` (default — a shared, service-principal-readable curated pool). `"obo"` is the reserved switch point for per-user skill volumes and is not wired yet (falls back to `"sp"` with a warning).
+
+***
+
+### skillsVolume?[​](#skillsvolume "Direct link to skillsVolume?")
+
+```ts
+optional skillsVolume: string;
+
+```
+
+Unity Catalog Volume path for catalog-sourced skills (e.g. `/Volumes/<catalog>/<schema>/<volume>`). Falls back to the `DATABRICKS_VOLUME_AGENT_SKILLS` env var. Skills at `<volume>/<name>/SKILL.md` are discovered at boot and on `reload()` and read as the service principal.
+
+***
+
 ### telemetry?[​](#telemetry "Direct link to telemetry?")
 
 ```ts

package/docs/api/appkit/Interface.RegisteredAgent.md

@@ -78,6 +78,17 @@ name: string;
 
 ***
 
+### skills?[​](#skills "Direct link to skills?")
+
+```ts
+optional skills: ResolvedSkillCatalog;
+
+```
+
+Resolved per-agent skill catalog (visibility + collision rules applied). Present when any skill is visible to this agent; drives the always-on prompt catalog and `load_skill` dispatch.
+
+***
+
 ### toolIndex[​](#toolindex "Direct link to toolIndex")
 
 ```ts

package/docs/api/appkit/Interface.Schema.md

@@ -1,4 +1,12 @@
-# Interface: Schema
+# Interface: Schema\<TTableName>
+
+One finalized schema. `TTableName` keeps the declared names in the type, so configuration that addresses a table by name is checked against the schema it was written for. Code that accepts any schema uses the default.
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter                  | Default type |
+| ------------------------------- | ------------ |
+| `TTableName` *extends* `string` | `string`     |
 
 ## Properties[​](#properties "Direct link to Properties")
 
@@ -23,6 +31,6 @@ readonly $schemaName: string;
 ### $tables[​](#tables "Direct link to $tables")
 
 ```ts
-readonly $tables: Readonly<Record<string, AppKitTable>>;
+readonly $tables: Readonly<Record<TTableName, AppKitTable>>;
 
 ```

package/docs/api/appkit/TypeAlias.IDatabaseConfig.md

@@ -2,6 +2,8 @@
 
 ```ts
 type IDatabaseConfig<TSchema> = {
+  crudRoutes?: CrudRoutesConfig<TSchema>;
+  hooks?: { readonly [TTable in SchemaTableName<TSchema>]?: { serialize?: ReadSerializer } };
   schema: TSchema;
 };
 
@@ -17,6 +19,24 @@ Configuration for one schema-bound DatabasePlugin instance.
 
 ## Properties[​](#properties "Direct link to Properties")
 
+### crudRoutes?[​](#crudroutes "Direct link to crudRoutes?")
+
+```ts
+readonly optional crudRoutes: CrudRoutesConfig<TSchema>;
+
+```
+
+***
+
+### hooks?[​](#hooks "Direct link to hooks?")
+
+```ts
+readonly optional hooks: { readonly [TTable in SchemaTableName<TSchema>]?: { serialize?: ReadSerializer } };
+
+```
+
+***
+
 ### schema[​](#schema "Direct link to schema")
 
 ```ts

package/docs/api/appkit/TypeAlias.ResolvedToolEntry.md

@@ -27,6 +27,12 @@ type ResolvedToolEntry =
   def: AgentToolDefinition;
   source: "hosted-supervisor";
   spec: SupervisorTool;
+}
+  | {
+  builtin: "load_skill" | "read_skill_file";
+  catalog: ResolvedSkillCatalog;
+  def: AgentToolDefinition;
+  source: "skill";
 };
 
 ```
@@ -194,3 +200,43 @@ Adapter-side hosted tool (executed by the model-host, not by the Node process).
 spec: SupervisorTool;
 
 ```
+
+```ts
+{
+  builtin: "load_skill" | "read_skill_file";
+  catalog: ResolvedSkillCatalog;
+  def: AgentToolDefinition;
+  source: "skill";
+}
+
+```
+
+### builtin[​](#builtin "Direct link to builtin")
+
+```ts
+builtin: "load_skill" | "read_skill_file";
+
+```
+
+### catalog[​](#catalog "Direct link to catalog")
+
+```ts
+catalog: ResolvedSkillCatalog;
+
+```
+
+### def[​](#def-5 "Direct link to def")
+
+```ts
+def: AgentToolDefinition;
+
+```
+
+### source[​](#source-5 "Direct link to source")
+
+```ts
+source: "skill";
+
+```
+
+Built-in skill tools (`load_skill`, `read_skill_file`) injected into any agent that has a visible skill catalog. Executed in-process by the agents plugin against the agent's resolved catalog; read-only, so they bypass the approval gate.

package/docs/api/appkit.md

@@ -74,7 +74,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md)                             | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements().                                                                                                                                                                                                                                                                                                                           |
 | [RunAgentInput](./docs/api/appkit/Interface.RunAgentInput.md)                                         | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [RunAgentResult](./docs/api/appkit/Interface.RunAgentResult.md)                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| [Schema](./docs/api/appkit/Interface.Schema.md)                                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| [Schema](./docs/api/appkit/Interface.Schema.md)                                                       | One finalized schema. `TTableName` keeps the declared names in the type, so configuration that addresses a table by name is checked against the schema it was written for. Code that accepts any schema uses the default.                                                                                                                                                                                                                                     |
 | [SearchRequest](./docs/api/appkit/Interface.SearchRequest.md)                                         | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [SearchResponse](./docs/api/appkit/Interface.SearchResponse.md)                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [SearchResult](./docs/api/appkit/Interface.SearchResult.md)                                           | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
@@ -155,7 +155,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [createWorkspaceClient](./docs/api/appkit/Function.createWorkspaceClient.md)           | Construct an AppKit workspace client.                                                                                                                                                                                                                                                                                        |
 | [database](./docs/api/appkit/Function.database.md)                                     | Create a typed database plugin registration for a finalized schema.                                                                                                                                                                                                                                                          |
 | [defineManifest](./docs/api/appkit/Function.defineManifest.md)                         | Validates a raw manifest (typically a `manifest.json` import) against the canonical Zod schema and returns it as a strict [PluginManifest](./docs/api/appkit/Interface.PluginManifest.md).                                                                                                                             |
-| [defineSchema](./docs/api/appkit/Function.defineSchema.md)                             | -                                                                                                                                                                                                                                                                                                                            |
+| [defineSchema](./docs/api/appkit/Function.defineSchema.md)                             | Compile one declared schema. The returned type keeps the table names the builder returned, so `crudRoutes` and `hooks` can name only real tables.                                                                                                                                                                            |
 | [defineTool](./docs/api/appkit/Function.defineTool.md)                                 | Defines a single tool entry for a plugin's internal registry.                                                                                                                                                                                                                                                                |
 | [enumColumn](./docs/api/appkit/Function.enumColumn.md)                                 | -                                                                                                                                                                                                                                                                                                                            |
 | [executeFromRegistry](./docs/api/appkit/Function.executeFromRegistry.md)               | Validates tool-call arguments against the entry's schema and invokes its handler. On validation failure, returns an LLM-friendly error string (matching the behavior of `tool()`) rather than throwing, so the model can self-correct on its next turn.                                                                      |

package/docs/plugins/agents.md

@@ -36,7 +36,7 @@ That alone gives you a live HTTP server with `POST /invocations` (and its alias
 
 ## Level 1: drop a markdown agent package[​](#level-1-drop-a-markdown-agent-package "Direct link to Level 1: drop a markdown agent package")
 
-Each agent lives in its own folder under `server/agents/` with entry file `agent.md`. A folder is an agent only if it holds an entry file (`agent.md` or `agent.ts`); a folder without one is skipped, so per-agent asset folders like `skills/` sit beside the entry.
+Each agent lives in its own folder under `server/agents/` with entry file `agent.md`. A folder is an agent only if it holds an entry file (`agent.md` or `agent.ts`); a folder without one is skipped, so per-agent asset folders sit beside the entry — notably a `skills/` folder holding [Skills](#skills) (on-demand instruction packs the agent loads by name). A shared `server/agents/skills/` folder holds skills available to any agent.
 
 ```text
 my-app/
@@ -211,6 +211,69 @@ await createApp({
 
 Put `supervisor`, `researcher`, and `writer` in their own `server/agents/<id>/agent.ts` folders (default export each) — a markdown parent can also delegate to a code child in a sibling folder via `agents: [helper]` frontmatter. Each key in `agents: {...}` on an `AgentDefinition` becomes an `agent-<key>` tool on the parent. When invoked, the agents plugin runs the child's adapter with a fresh message list (no shared thread state) and returns the aggregated text. Cycles in a code agent's inline `agents: {}` graph are rejected at load (`createAgent`); markdown `agents:` delegation rejects self-references at load and bounds deeper cycles at runtime via `limits.maxSubAgentDepth`.
 
+## Skills[​](#skills "Direct link to Skills")
+
+Skills are on-demand instruction packs — the same `SKILL.md` format Claude Code and Cursor use. Only each skill's `name` + `description` sit in the system prompt (always-on, cheap); the full body loads on demand when the agent (or the user) invokes it. This works on any Databricks-served model — AppKit implements the disclosure itself, so it doesn't depend on a provider-native skills feature.
+
+A skill is a directory with a `SKILL.md` plus any bundled reference files:
+
+```text
+config/agents/
+  skills/                    # shared pool — any agent can opt in
+    pdf-forms/
+      SKILL.md
+      reference.md
+  planner/
+    agent.md
+    skills/                  # private to the `planner` agent
+      house-style/
+        SKILL.md
+
+```
+
+```md
+---
+name: pdf-forms
+description: Fill and validate PDF form fields from a data record.
+---
+
+To fill a PDF form:
+
+1. Read `reference.md` for the field-name conventions.
+2. ...
+
+```
+
+`name` and `description` are required; `license`, `allowed-tools`, and `metadata` are accepted for compatibility with skills authored elsewhere. Unknown keys warn and are ignored.
+
+### Visibility[​](#visibility "Direct link to Visibility")
+
+* **Per-agent skills** (`config/agents/<id>/skills/`) are always visible to that agent.
+* **Global skills** (`config/agents/skills/`, and catalog-volume skills) are **opt-in**: list them in the agent's frontmatter, `skills: [pdf-forms]`. Set `autoInheritSkills: true` (or `{ file, code }`) on the plugin to make every global skill visible without listing — off by default so each agent's always-on catalog stays lean.
+
+### How the agent uses a skill[​](#how-the-agent-uses-a-skill "Direct link to How the agent uses a skill")
+
+Two read-only built-in tools are injected into any agent that has a visible catalog:
+
+* `load_skill(skill)` — returns the skill's full instructions plus a manifest of its bundled files.
+* `read_skill_file(skill, path)` — returns the contents of one of those bundled files.
+
+The model calls `load_skill` on its own when a task matches a skill's description. A **user** can force a specific skill for a turn with the `/skill-name` prefix in chat (or the `send(message, { skill })` option on `useAgentChat`); the skill's instructions are injected into that turn deterministically, and `load_skill` remains available for auto-selection. The client reads the per-agent catalog from the plugin's `clientConfig()` payload to power a picker.
+
+### Catalog skills (Unity Catalog Volume)[​](#catalog-skills-unity-catalog-volume "Direct link to Catalog skills (Unity Catalog Volume)")
+
+Point `skillsVolume` (or the `DATABRICKS_VOLUME_AGENT_SKILLS` env var) at a UC Volume laid out the same way — `<volume>/<name>/SKILL.md`. Catalog skills are discovered at boot and on `reload()`, merged into the shared global pool, and read as the **service principal** (`skillCredentialMode` defaults to `"sp"`). They're intended as a shared, curated pool; per-user (OBO) skill volumes are not wired yet. Declaring the optional `volume` resource in the manifest lets the scaffolder grant the SP read access.
+
+### Name collisions[​](#name-collisions "Direct link to Name collisions")
+
+Skill names are addressed bare. If two sources provide the same name, each becomes a qualified `<scope>:name` (`agent:`, `bundle:`, `volume:`) and the bare name is rejected as ambiguous with the alternatives listed. Two skills with the same name from the *same* source is a boot-time error.
+
+### v1 caveats[​](#v1-caveats "Direct link to v1 caveats")
+
+* **Scripts are not executed.** A skill may reference `scripts/foo.py`; v1 loads prose and reference docs only.
+* **`allowed-tools` is advisory.** It's surfaced as a hint in the loaded skill, not enforced — loading a skill does not restrict the agent's callable tools. It is not a sandbox.
+* **Skill bodies are not per-user access-controlled** (they read as the SP). Keep user-sensitive content out of skill bodies.
+
 ## Level 5: standalone (no `createApp`)[​](#level-5-standalone-no-createapp "Direct link to level-5-standalone-no-createapp")
 
 ```ts
@@ -427,6 +490,9 @@ agents({
   defaultModel?: AgentAdapter | Promise<AgentAdapter> | string,
   tools?: Record<string, AgentTool>,
   autoInheritTools?: boolean | { file?: boolean, code?: boolean },
+  autoInheritSkills?: boolean | { file?: boolean, code?: boolean }, // default off
+  skillsVolume?: string,        // UC Volume for catalog skills; falls back to DATABRICKS_VOLUME_AGENT_SKILLS
+  skillCredentialMode?: "sp" | "obo", // default "sp" (see Skills)
   threadStore?: ThreadStore,    // default in-memory
   baseSystemPrompt?: false | string | (ctx: PromptContext) => string,
   mcp?: {
@@ -628,6 +694,7 @@ appkit.agents.getThreads(userId);   // list user's threads
 | `endpoint`         | string          | Model serving endpoint name. Shortcut for `model`.                                                                                                                                                                                                                                              |
 | `model`            | string          | Same as `endpoint`; either works.                                                                                                                                                                                                                                                               |
 | `tools`            | array           | Unified tool list. Entries are `plugin:<name>` / `plugin:<name>: [t1, t2]` / `plugin:<name>: { only, except, rename, prefix }` for plugin tools, or a bare `<key>` resolved against `agents({ tools: {...} })` for ambient tools. See "Level 2: scope tools in frontmatter" above for examples. |
+| `skills`           | array           | Names of global skills (shared `skills/` pool or catalog volume) to make visible to this agent. Per-agent skills under `<id>/skills/` are always visible. See [Skills](#skills).                                                                                                                |
 | `default`          | boolean         | First agent id (sorted order) with `default: true` becomes the default agent.                                                                                                                                                                                                                   |
 | `agents`           | array           | Sub-agent ids (sibling folders) to delegate to; each becomes an `agent-<id>` tool. Resolves against other markdown and code agents.                                                                                                                                                             |
 | `maxSteps`         | number          | Adapter max-step hint.                                                                                                                                                                                                                                                                          |

package/llms.txt

@@ -93,7 +93,7 @@ npx @databricks/appkit docs <query>
 - [Function: createWorkspaceClient()](./docs/api/appkit/Function.createWorkspaceClient.md): Construct an AppKit workspace client.
 - [Function: database()](./docs/api/appkit/Function.database.md): Create a typed database plugin registration for a finalized schema.
 - [Function: defineManifest()](./docs/api/appkit/Function.defineManifest.md): Validates a raw manifest (typically a manifest.json import) against the
-- [Function: defineSchema()](./docs/api/appkit/Function.defineSchema.md): Parameters
+- [Function: defineSchema()](./docs/api/appkit/Function.defineSchema.md): Compile one declared schema. The returned type keeps the table names the
 - [Function: defineTool()](./docs/api/appkit/Function.defineTool.md): Defines a single tool entry for a plugin's internal registry.
 - [Function: enumColumn()](./docs/api/appkit/Function.enumColumn.md): Parameters
 - [Function: executeFromRegistry()](./docs/api/appkit/Function.executeFromRegistry.md): Validates tool-call arguments against the entry's schema and invokes its
@@ -171,7 +171,7 @@ npx @databricks/appkit docs <query>
 - [Interface: ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md): Declares a resource requirement for a plugin.
 - [Interface: RunAgentInput](./docs/api/appkit/Interface.RunAgentInput.md): Properties
 - [Interface: RunAgentResult](./docs/api/appkit/Interface.RunAgentResult.md): Properties
-- [Interface: Schema](./docs/api/appkit/Interface.Schema.md): Properties
+- [Interface: Schema<TTableName>](./docs/api/appkit/Interface.Schema.md): One finalized schema. TTableName keeps the declared names in the type, so
 - [Interface: SearchRequest](./docs/api/appkit/Interface.SearchRequest.md): Properties
 - [Interface: SearchResponse<T>](./docs/api/appkit/Interface.SearchResponse.md): Type Parameters
 - [Interface: SearchResult<T>](./docs/api/appkit/Interface.SearchResult.md): Type Parameters

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit",
   "type": "module",
-  "version": "0.66.1",
+  "version": "0.68.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {