Uh oh!
There was an error while loading. Please reload this page.
feat(appkit): Agent Skills (v1) — SKILL.md progressive disclosure for agents - #532
Draft
MarioCadenas wants to merge 8 commits into
Draft
feat(appkit): Agent Skills (v1) — SKILL.md progressive disclosure for agents#532MarioCadenas wants to merge 8 commits into
MarioCadenas wants to merge 8 commits into
Conversation
MarioCadenasforce-pushed
the
feat/agent-skills
branch
from
August 13, 2026 13:47
0bc20d6 to
3dc4e7fCompareContributor
📦 Bundle size reportCompared against
|
| dist | raw | gzip |
|---|---|---|
| JS (runtime) | 906 KB (+37 KB) | 317 KB (+14 KB) |
| Type declarations | 326 KB (+12 KB) | 114 KB (+4.6 KB) |
| Source maps | 1.8 MB (+70 KB) | 591 KB (+25 KB) |
| Other | 11 KB | 3.7 KB |
| Total | 3.0 MB (+118 KB) | 1.0 MB (+44 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.2 KB) | 457 B | 56 KB (+7.2 KB) | external | 164 KB (+21 KB) |
./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 |
./type-generator | index.js | initial | 21 KB |
@databricks/appkit-ui
npm tarball (packed): 343 KB (+466 B) — gzipped download (dist + bin; excludes release-only docs/NOTICE).
| dist | raw | gzip |
|---|---|---|
| JS (runtime) | 390 KB (+316 B) | 131 KB (+159 B) |
| Type declarations | 228 KB (+300 B) | 83 KB (+130 B) |
| Source maps | 754 KB (+906 B) | 248 KB (+295 B) |
| CSS | 16 KB (-462 B) | 3.2 KB (-90 B) |
| Total | 1.4 MB (+1.0 KB) | 465 KB (+494 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 (+248 B) | 49 KB | 481 KB (+248 B) | 1.3 MB | 175 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 |
Contributor
🤖 AppKit PR bot🔬 Run evalsStart an eval for this PR from the evals-monitor app: Go to Evals Monitor → 📦 Try this PR's app templateScaffolds a new app from this PR's SDK build. Run it in any folder (requires the GitHub CLI — gh run download 32261036570 -R databricks/appkit -n appkit-template-0.61.1-pr.fa9865d-feat-agent-skills-532 -D appkit-pr-532 \
&& unzip -o "appkit-pr-532/appkit-template-0.61.1-pr.fa9865d-feat-agent-skills-532.zip" -d "appkit-pr-532" \
&& databricks apps init --template "appkit-pr-532"The template pins |
…er/agents
Every agent is a folder under server/agents/<id>/ holding agent.md (markdown)
or agent.ts (code); the folder name is the id.
- Code loader scans <id>/agent.{ts,tsx,js,mjs}, built-first: a relative dir
resolves dist/<name>|build/<name> before source, an absolute dir is verbatim,
so a bundled server never imports .ts under plain Node.
- Markdown loader skips folders without agent.md so code + asset dirs coexist;
drop the RESERVED_DIRS list.
- One `dir` knob (default server/agents) feeds both loaders; codeAgentsDir
retired. config/agents is read as a deprecated fallback (per-agent merge, new
location wins, one-time warning); cross-location sub-agent refs resolve.
- Cross-kind sub-agent references resolve by folder id.
- Migrate template, dev-playground, docs, and tests to the folder layout; add
fallback / built-first / cross-dir test coverage.
Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
Follow-up to the review + inconsistency fan-out: - findEntryFile now rethrows non-ENOENT/ENOTDIR errors (an unreadable agent folder no longer silently vanishes in prod). - Clearer discovered-vs-markdown collision message (covers the cross-root config/agents fallback case, not just one folder). - Template tsdown: scope clean:true to the agents case so a non-agents scaffold's build config is unchanged. - Docs: fix DATABRICKS_SERVING_ENDPOINT_NAME, the auto-inherit default (off for both), cycle-rejection scope, /api/agents/approve path, defaultAgent precedence, dir:false wording, stale-dist note, and add the agents/generationParams frontmatter keys + toolCallTimeoutMs limit. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
Ships the server build wiring from the package so a scaffolded app's
tsdown.server.config.ts is a one-liner instead of hand-maintained config:
import { appkitServerConfig } from '@databricks/appkit/tsdown';
export default appkitServerConfig();
- appkitServerConfig(overrides?, opts?) auto-detects server/agents/<id>/agent.ts
and adds the entry glob + clean only when code agents exist.
- Object overrides merge with intent (entry unioned so the agent glob can't be
clobbered, external composed, other keys win); a function override receives
the computed base for full control.
- Dependency-free (node: builtins only) so it stays lean at build time.
- New ./tsdown export subpath (attw + publint clean); template drops its
{{if .plugins.agents}} conditional.
Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>Markdown agents need no build change; code agents require the server build to emit them (dev via tsx hides this — only a bundled build breaks). Points at the appkitServerConfig() preset as the one-line fix, notes the manual entry-glob alternative, and the startup warning that catches a forgotten build change. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
…ion .ts-only From the /simplify pass: - Extract agentDirNames() so both loaders share one folder-selection policy (dir + symlink) instead of duplicating the subtle filter + comment. - Code-agent source detection is .ts-only (resolveCodeAgentsDir source exts + hasCodeAgentSources), matching the build entry glob — an agent.tsx would otherwise load in dev but never be emitted for a prod bundle. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
…ents) Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
MarioCadenasforce-pushed
the
feat/agent-skills
branch
from
August 19, 2026 13:56
3dc4e7f to
baad708Compare…xtures Exercise the previously-untested skill sources/paths in the reference app: - global `bullet-brief` skill; helper opts into it (multi-entry menu on a code agent) - per-agent `query/skills/routing-brief` (bundle-agent source + bundled reference.md) - per-agent `query/skills/haiku` collides with global `haiku` (query opts in), forcing qualified agent:haiku / bundle:haiku addressing - add `query` to the /agent page picker so its skills surface in the input Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
MarioCadenasforce-pushed
the
agents-discovery-dx
branch
from
August 20, 2026 12:07
643b7f9 to
4b886caCompare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Agent Skills (v1)
Runtime Agent Skills for the
agentsplugin — theSKILL.mdformat Claude Code / Cursor use, brought to AppKit agents. Only each skill'sname+descriptionsit 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(frontmattername+description, Markdown body) plus optional bundled reference files. Frontmatter is an Anthropic-format superset (also tolerateslicense,allowed-tools,metadata); unknown keys warn, not error — so skills authored elsewhere drop in.How it works
name+descriptionis injected into the agent's system prompt.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)./skill-namein chat (oruseAgentChat'ssend(msg, { skill })).Sources & visibility
config/agents/skills/, per-agentconfig/agents/<id>/skills/, and a catalog UC Volume (skillsVolume/DATABRICKS_VOLUME_AGENT_SKILLS), read as the service principal.skills: [...]frontmatter (orautoInheritSkills).<scope>:name; the bare name errors as ambiguous.Commits (phased, independently reviewable)
feat(appkit): load and resolve agent skills from bundle sources— model, parser, loader, per-agent catalog resolutionfeat(appkit): expose skills to agents via prompt catalog and load_skill— disclosure + built-in tools (bundle e2e)feat(appkit): source agent skills from a Unity Catalog volume— catalog source, SP-readfeat(appkit): let users load skills from chat (/skill-name + picker)— client UX + forced loadfeat(appkit): document agent skills, wire sub-agents, ship example skilldev-playgroundcommits (ahaikudemo skill + a/-triggered skill menu) for hands-on testing.Try it in dev-playground
pnpm --filter=dev-playground dev, open/agent(Helper agent):/→ 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 theload_skilltool call).Tests & verification
New coverage across
skills.test.ts,dispatch-tool-call,skill-volume,skill-client, and theuse-agent-chathook. 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-toolsenforcement (advisory only in v1); per-user (OBO) skill volumes; TTL refresh of volume listings; marketplace / end-user-uploaded skills; standalonerunAgentskill parity.