feat(appkit): Agent Skills (v1) — SKILL.md progressive disclosure for agents

[MarioCadenas]

Agent Skills (v1)

Runtime Agent Skills for the agents plugin — the SKILL.md format Claude Code / Cursor use, brought to AppKit agents. Only each skill's name + description sit in the system prompt (always-on, cheap); the full body loads on demand. Works on any Databricks-served model — AppKit implements the progressive disclosure itself, so it doesn't depend on a provider-native skills feature. Fills the seam the loader already reserved (RESERVED_DIRS = new Set(["skills"])).

Not to be confused with the dev-time "Databricks Agent Skills" product (Claude Code skills for building apps) — this is a runtime capability of deployed agents.

What a skill is

A directory with a SKILL.md (frontmatter name + description, Markdown body) plus optional bundled reference files. Frontmatter is an Anthropic-format superset (also tolerates license, allowed-tools, metadata); unknown keys warn, not error — so skills authored elsewhere drop in.

How it works

• Every visible skill's name + description is injected into the agent's system prompt.
• Two read-only built-in tools are added to any agent with a catalog: load_skill(skill) returns the body + a manifest of bundled files; read_skill_file(skill, path) reads one of those files (through a directory-containment guard).
• The model auto-loads a skill when a task matches; a user can force one for a turn with /skill-name in chat (or useAgentChat's send(msg, { skill })).

Sources & visibility

• Global bundle config/agents/skills/, per-agent config/agents/<id>/skills/, and a catalog UC Volume (skillsVolume / DATABRICKS_VOLUME_AGENT_SKILLS), read as the service principal.
• Per-agent skills are always visible; global skills are opt-in via skills: [...] frontmatter (or autoInheritSkills).
• Name collisions resolve to qualified <scope>:name; the bare name errors as ambiguous.

Commits (phased, independently reviewable)

1. feat(appkit): load and resolve agent skills from bundle sources — model, parser, loader, per-agent catalog resolution
2. feat(appkit): expose skills to agents via prompt catalog and load_skill — disclosure + built-in tools (bundle e2e)
3. feat(appkit): source agent skills from a Unity Catalog volume — catalog source, SP-read
4. feat(appkit): let users load skills from chat (/skill-name + picker) — client UX + forced load
5. feat(appkit): document agent skills, wire sub-agents, ship example skill

• plus a plugin-catalog sync and two dev-playground commits (a haiku demo skill + a /-triggered skill menu) for hands-on testing.

Try it in dev-playground

pnpm --filter=dev-playground dev, open /agent (Helper agent):

• Type / → a menu of the agent's skills (/haiku); ↑/↓ + Enter/Tab to insert.
• /haiku what's the weather in Paris? forces the skill; "give me a haiku about NYC taxi trips" triggers auto-load (watch the load_skill tool call).

Tests & verification

New coverage across skills.test.ts, dispatch-tool-call, skill-volume, skill-client, and the use-agent-chat hook. Full appkit (3075) and appkit-ui (366) suites pass; all packages typecheck; docs build succeeds.

Deferred to v2 (non-goals here)

Script/code execution from skills; allowed-tools enforcement (advisory only in v1); per-user (OBO) skill volumes; TTL refresh of volume listings; marketplace / end-user-uploaded skills; standalone runAgent skill parity.

[github-actions]

📦 Bundle size report

Compared against bundle-size-baseline.json (main).

@databricks/appkit

npm tarball (packed): 909 KB (+36 KB) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist	raw	gzip
JS (runtime)	929 KB (+37 KB)	326 KB (+14 KB)
Type declarations	351 KB (+11 KB)	122 KB (+4.3 KB)
Source maps	1.8 MB (+68 KB)	611 KB (+24 KB)
Other	11 KB	3.7 KB
Total	3.1 MB (+116 KB)	1.0 MB (+43 KB)

Per-entry composition (own code — deps external (as shipped))

Entry	Initial (gz)	Lazy (gz)	Total (gz)	node_modules (min)	Own code (min)
.	88 KB	2.5 KB	91 KB	external	288 KB
./beta	56 KB (+7.1 KB)	457 B	56 KB (+7.1 KB)	external	164 KB (+21 KB)
./testing	17 KB	0 B	17 KB	external	50 KB
./tsdown	520 B	0 B	520 B	external	813 B
./type-generator	21 KB	0 B	21 KB	external	61 KB

Chunks:

Entry	Chunk	Load	Size (gz)
.	index.js	initial	84 KB
.	utils.js	initial	4.0 KB
.	remote-tunnel-manager.js	lazy	2.5 KB
./beta	beta.js	initial	40 KB
./beta	stream-manager.js	initial	5.8 KB
./beta	wide-event-emitter.js	initial	3.2 KB
./beta	databricks.js	initial	3.0 KB
./beta	configuration.js	initial	2.1 KB
./beta	service-context.js	initial	1.3 KB
./beta	client.js	initial	434 B
./beta	client-options.js	initial	220 B
./beta	supervisor-api.js	lazy	192 B
./beta	databricks.js	lazy	142 B
./beta	index.js	lazy	123 B
./testing	index.js	initial	17 KB
./tsdown	index.js	initial	520 B
./type-generator	index.js	initial	21 KB

@databricks/appkit-ui

npm tarball (packed): 349 KB (+751 B) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist	raw	gzip
JS (runtime)	394 KB (+316 B)	132 KB (+158 B)
Type declarations	229 KB (+300 B)	84 KB (+130 B)
Source maps	765 KB (+1.2 KB)	253 KB (+492 B)
CSS	16 KB	3.2 KB
Total	1.4 MB (+1.8 KB)	471 KB (+780 B)

Per-entry composition (consumer bundle — deps bundled, peerDeps external)

Entry	Initial (gz)	Lazy (gz)	Total (gz)	node_modules (min)	Own code (min)
./js	5.3 KB	49 KB	55 KB	208 KB	14 KB
./js/beta	20 B	0 B	20 B	0 B	0 B
./react	432 KB (+120 B)	49 KB	481 KB (+120 B)	1.3 MB	177 KB (+168 B)
./react/beta	1.0 KB	0 B	1.0 KB	0 B	1.9 KB

Chunks:

Entry	Chunk	Load	Size (gz)
./js	index.js	initial	5.2 KB
./js	chunk	initial	120 B
./js	apache-arrow	lazy	49 KB
./js/beta	beta.js	initial	20 B
./react	index.js	initial	430 KB
./react	tslib	initial	2.1 KB
./react	apache-arrow	lazy	49 KB
./react/beta	beta.js	initial	1.0 KB

[github-actions]

🤖 AppKit PR bot

🔬 Run evals

Start an eval for this PR from the evals-monitor app: Go to Evals Monitor →

📦 Try this PR's app template

Scaffolds a new app from this PR's SDK build. Run it in any folder (requires the GitHub CLI — gh auth login — and the Databricks CLI):

gh run download 32470045125 -R databricks/appkit -n appkit-template-0.63.0-pr.2ca1159-feat-agent-skills-532 -D appkit-pr-532 \
  && unzip -o "appkit-pr-532/appkit-template-0.63.0-pr.2ca1159-feat-agent-skills-532.zip" -d "appkit-pr-532" \
  && databricks apps init --template "appkit-pr-532"

The template pins @databricks/appkit and @databricks/appkit-ui to tarballs built from this branch, so the scaffolded app runs against this PR's code.

[MarioCadenas]

Split into two stacked PRs for easier review — this PR is superseded:

• feat(appkit): Agent Skills v1 — SKILL.md progressive disclosure (SDK, 1/2 of #532) #543 — SDK feature (skills engine + agents-plugin integration + appkit-ui hook + docs) → base main, merges first
• test(playground): Agent Skills demo — playground + template fixtures (2/2 of #532) #544 — playground + template demo fixtures → stacked on feat(appkit): Agent Skills v1 — SKILL.md progressive disclosure (SDK, 1/2 of #532) #543, auto-retargets to main once feat(appkit): Agent Skills v1 — SKILL.md progressive disclosure (SDK, 1/2 of #532) #543 merges

Both are rebased onto current main (includes #485 defineManifest), so they merge cleanly — unlike this branch, which is CONFLICTING. Suggest closing this in favour of the stack once #543/#544 land.

[MarioCadenas]

Superseded by the split stack: #543 (SDK, base main) → merge first, then #544 (playground + template fixtures, stacked). Both rebased onto current main and mergeable. Closing this one.