Add AppKit support and databricks-agent-skills integration (experimental)#533
Merged
calreynolds merged 4 commits intoMay 13, 2026
Conversation
Equivalent of databricks-solutions#356 (which targets main), adapted for the experimental branch: - Rename `databricks-app-python` → `databricks-apps-python` (plural) for the bundled skill directory, baselines, manifests, builder-app refs, install scripts, and cross-skill mentions. - `databricks-apps-python/SKILL.md` now leads with AppKit (TypeScript + React SDK) as the recommended approach for new apps, with Python frameworks (Dash, Streamlit, Gradio, Flask, FastAPI, Reflex) demoted to an explicit alternative. Frontmatter `name` and H1 title updated to match. - `install.sh` and `install.ps1` fetch and install skills from `databricks/databricks-agent-skills` (`databricks`, `databricks-apps`, `databricks-lakebase`) via a single GitHub API tree call. New `AGENT_SKILLS` variable supports `source:install-name` syntax (e.g. `databricks-core:databricks`) so the install directory can differ from the upstream skill path. - Preserves experimental's polish: keeps `6-cli-approach.md` (not MCP) and references `databricks-lakebase-autoscale` (since `databricks-lakebase-provisioned` was removed on experimental). Co-authored-by: Isaac
7 tasks
GPT 5.4 xhigh and Gemini 3.1 Pro both flagged the new short agent-skill names triggering latent bugs in the install scripts. Three fixes: 1. install.sh `_is_preselected`: `grep -qw` treats `-` as a word boundary, so checking for `databricks` would falsely match `databricks-jobs`, `databricks-apps`, etc. Strip `source:` prefix from each preselected entry and use `grep -Fxq` for exact whole-line equality. Same fix applied to the deselection cleanup at the cleanup loop. 2. install.ps1: `$preselected -contains "databricks"` is exact equality on array elements, so it never matched the `"databricks-core:databricks"` entry seeded by the app-developer profile — the Agent: Databricks checkbox was never auto-preselected. Normalize `$preselected` by stripping `source:` prefixes once before the menu is built. 3. install.sh/ps1: the "Agent skills (N) -> ..." success line ran unconditionally, even when the GitHub tree fetch failed or every per-skill download warned and was rolled back. Track an `agent_success`/`$agentSuccess` counter and only print the success line when all selected agent skills installed; print a warning when only some succeeded. Co-authored-by: Isaac
…ale dirs Two more ACE review findings, both real: 1. The path-extraction regex `"path":"skills/..."` (no space) does NOT match the GitHub tree API's actual response, which is pretty-printed as `"path": "skills/..."` (space after colon). Result: the installer would warn "Could not fetch agent skill" for every entry and install nothing. Fix: collapse the JSON whitespace before regex extraction, and switch from the `grep '\.'` heuristic to matching the adjacent `"type": "blob"` field so directory entries are correctly skipped. 2. Reinstalls reused the existing $dest_dir / $destDir without clearing it, so files removed upstream would persist locally across upgrades. Fix: `rm -rf` / `Remove-Item -Recurse` the destination before each skill is downloaded. Co-authored-by: Isaac
ACE iteration 2 findings: - Gemini caught that the `grep -qw` word-boundary bug I fixed in `_is_preselected` still bit the resolve_skills() bucketing chain (lines 918/920/922). Passing `--skills databricks` (a valid agent install-name) would match `databricks-app-apx` via the hyphen word-boundary on the APX branch and get misclassified. Switched all three buckets to exact match via `tr ' ' '\n' | grep -Fxq`, and rewrote the source:install-name lookup on line 923 with `-E` and a clean anchored alternation. - GPT caught that when the GitHub tree fetch fails entirely (`agent_tree` empty / `$agentTree` null), the summary branch emits nothing — neither OK nor "only N of M installed" — even though zero of N agent skills were actually installed. Added an `else` branch that emits a `0 of $agent_count installed` warning. Out of scope (flagged but not addressed): - GPT raised legacy-name compatibility for `databricks-app-python` → `databricks-apps-python`. The rename is intentional per the product decision; back-compat aliasing is a separate concern. Co-authored-by: Isaac
2 tasks
lennartkats-db
pushed a commit
to databricks/databricks-agent-skills
that referenced
this pull request
May 24, 2026
) ## Summary Adds an `experimental/` directory containing 19 agent skills from [databricks-solutions/ai-dev-kit](https://github.com/databricks-solutions/ai-dev-kit) `databricks-skills/`, imported as a snapshot on a **best-effort basis**. Excluded: `databricks-model-serving` (TODO #1b — different surface than stable, heavy MCP coupling) and `databricks-spark-declarative-pipelines` (TODO #5 — different surface than stable `databricks-pipelines`). `databricks-lakebase-provisioned` is not in the upstream `experimental` branch either, so absent here. The manifest now exposes both stable and experimental skills in a **single `skills` map**. Each entry carries a `repo_dir` field (`"skills"` or `"experimental"`) that points to the directory the skill lives in. Consumers derive experimental state from `repo_dir` — there is no parallel `experimental_skills` map and no per-skill `experimental` bool. Paired with [databricks/cli#5243](databricks/cli#5243) which teaches `databricks experimental aitools skills install` to: - read `repo_dir` and skip experimental entries by default, - install all of them with `--experimental`, - install one by name (with `--experimental` required and `-experimental` suffix on the install dir). ## Source Synced from [`f9b404b`](databricks-solutions/ai-dev-kit@f9b404b) on `databricks-solutions/ai-dev-kit:experimental`. Initial import was [`9c7a5b3`](databricks-solutions/ai-dev-kit@9c7a5b3) (head of [a-d-k PR #533](databricks-solutions/ai-dev-kit#533) on the `appkit-on-experimental` branch). PR #533 has since merged into `experimental` (`7b07f18`), and the branch has two further commits worth pulling: - [`0ebc38b`](databricks-solutions/ai-dev-kit@0ebc38b) "Surface silent failures in installer + dashboard skill" — updates `databricks-aibi-dashboards/SKILL.md` (CLI flag JSON-vs-flag form). - [`f9b404b`](databricks-solutions/ai-dev-kit@f9b404b) "Replace mas_manager.py with native supervisor-agents CLI" — updates `databricks-agent-bricks/SKILL.md` + `2-supervisor-agents.md` to the new supervisor-agents CLI group (Beta, CLI 0.299.2+); removes the 667-line `scripts/mas_manager.py` shim. Both pulled in commit `10baa35`. The fork branch's installer-side fixes (`5d2e6ac` / `39c349c` / `dd2257c`) are a-d-k tooling and don't touch `databricks-skills/`, so nothing to pull from there. ~~**Landing dependency**: a-d-k PR #533 should merge before this PR so the first periodic sync from a-d-k doesn't conflict.~~ **Resolved** — PR #533 merged upstream. The rename (`databricks-app-python` → `databricks-apps-python`) is preserved in the merged version, which is what prevents a 3rd skill-name collision with d-a-s's stable `databricks-apps`. ## Direction caveat — please read In the Apr 28 thread ([Slack link](https://databricks.slack.com/archives/C0AKALZU65P/p1778088227285599?thread_ts=1774540245.454779&cid=C0AKALZU65P)), Dustin's stated plan was to move `databricks-agent-skills` skills **into** `ai-dev-kit`'s `experimental` branch as defaults. **This PR goes the other direction** (a-d-k content → d-a-s/experimental). I don't see any d-a-s commits from Dustin yet, and the timing has slipped. Opening this so we have something concrete to iterate on — happy to drop it if the original direction is still preferred. ## TODOs / caveats for iteration 1. **Name collisions.** Resolved in this PR: - **1a. `databricks-jobs` — merged into stable.** Imported the comprehensive reference content from a-d-k's `databricks-jobs` skill into `skills/databricks-jobs/`, bumping version to `0.2.0`. The merged skill keeps stable's scaffolding workflow + `parent: databricks-core` hierarchy + Codex `agents/openai.yaml` + compatibility note, and adds the experimental's full task-types reference (9 types), trigger types (6), notifications/health/retries/queues, and 7 worked end-to-end examples. Layered structure: SKILL.md as overview + four reference files (`task-types.md`, `triggers-schedules.md`, `notifications-monitoring.md`, `examples.md`). Cleanups during merge: dropped trigger-spam description, normalized `/Workspace/Users/user@example.com/...` paths to `/Workspace/Shared/...`. The experimental copy is removed. With the single-map manifest shape, collisions are no longer possible — `_add_skill` raises if the same skill name shows up under both `skills/` and `experimental/`, so any future drift fails generation loudly. - **1b. `databricks-model-serving` — dropped from this PR.** After a deep compare, the two skills cover almost entirely different surfaces: stable is **ops-focused** (manage existing endpoints via CLI: `serving-endpoints create/get/query/update-config/build-logs/put-ai-gateway/get-permissions/...`, AI Gateway, traffic config, app integration via `databricks-apps` skill); experimental is **dev-focused** (build & ship MLflow models / GenAI agents: autolog → `mlflow.pyfunc.log_model` → `databricks.agents.deploy()` → query, with full Classical ML / Custom PyFunc / `ResponsesAgent` + LangGraph / UCFunctionToolkit / VectorSearchRetrieverTool coverage). Near-zero content overlap. Experimental version also has heavy MCP-tool dependency (60+ refs to ai-dev-kit's `manage_serving_endpoint`, `manage_workspace_files`, `manage_jobs`, `manage_job_runs`, `execute_code` that don't exist in the d-a-s/`databricks experimental aitools` flow). Removed `experimental/databricks-model-serving/` from this PR; manifest regenerated. **Follow-up**: port the high-value dev-side content into the stable skill — classical-ml autolog patterns (`mlflow.{sklearn,xgboost,lightgbm,pytorch,tensorflow,spark}.autolog()`), Custom PyFunc signatures, `ResponsesAgent` pattern with the `create_text_output_item` helper-method gotcha, `UCFunctionToolkit` + `VectorSearchRetrieverTool` with resource passthrough for auth, the Foundation Model API endpoint table. Strip MCP refs; replace with CLI/SDK equivalents. Owners: @databricks/eng-apps-devex (per CODEOWNERS). 2. ~~**CODEOWNERS for `experimental/`**~~ **Resolved.** Per @simonfaltum review: the top 10 a-d-k contributors (>=10 commits at import time) are now Code Owners of `/experimental/` alongside the d-a-s maintainers (@lennartkats-db, @simonfaltum, @databricks/eng-apps-devex), so their review satisfies the Required-Code-Owner-Review branch protection. Maintainer review still works as an alternate path. 3. ~~**No sync mechanism with upstream a-d-k.**~~ **Resolved with a paired RFC.** Two-part plan: - **Pre-lock (this PR)**: periodic manual re-syncs from upstream `ai-dev-kit` into `experimental/`. Documented in `experimental/README.md`. - **Post-lock (follow-up)**: invert the direction. a-d-k becomes the consumer; `databricks-skills/imported/` in a-d-k is a `git subtree` of this repo's `experimental/`. RFC PR opened against a-d-k: databricks-solutions/ai-dev-kit#530 (draft). To make subtree work, d-a-s needs to publish an `experimental-only` branch via `git subtree split --prefix=experimental` after every push to main — that's a small workflow to add here in a follow-up PR. A one-shot preview branch `experimental-only-preview` was pushed to this repo to enable the RFC demo and should be deleted once the auto-publish workflow lands. 4. ~~**No agent metadata.**~~ **Resolved.** Imported skills install fine on Codex CLI — the missing `agents/openai.yaml` was a cosmetic gap, not a functional blocker (skill files still get copied; only the marketplace UI metadata is absent). `scripts/skills.py` now auto-generates `agents/openai.yaml` + copies shared assets for each experimental skill on `generate`, using SKILL.md frontmatter as the source. Stubs are only written when missing, so upstream a-d-k can override by shipping its own files in the skill. The auto-generated names are titlecased from the skill key — most look good (`Databricks Iceberg`, `Databricks Genie`); a few degrade gracefully (`Databricks Aibi Dashboards`). Refining those is a follow-up. 5. ~~**`databricks-pipelines` was deliberately excluded.**~~ **Resolved.** a-d-k doesn't ship a `databricks-pipelines` skill under that name, but it *does* ship `databricks-spark-declarative-pipelines` covering the same product. After a deep compare, that experimental version covers a different surface than stable: scaffolding (`databricks pipelines init` + bundle/MCP workflow A/B/C), DLT migration guide, language-selection rules, per-language performance reference. The stable skill covers feature reference (decision tree, common traps, format options, fine-grained per-feature × per-language refs). Partial overlap; experimental's DAB-coupled workflow is the exact concern Dustin flagged in the Apr 28 Slack thread for demo-generator flows. **Removed `experimental/databricks-spark-declarative-pipelines/` from this PR**. **Follow-up TODO** (post-merge): port the high-value pieces into stable `skills/databricks-pipelines/` — DLT migration guide, workflow A/B/C decision matrix, per-language performance reference, language-selection rules. Strip MCP-tool refs. Owners: @lennartkats-db / @camielstee-db (per CODEOWNERS). 6. ~~**`spark-python-data-source` naming exception.**~~ **Kept as-is.** The skill is about the OSS Apache Spark 4+ PySpark DataSource API (building custom connector libraries), not a Databricks product — only lightly flavored with Databricks idioms. The convention break is acceptable given the content. 7. ~~**Versioning.**~~ **Resolved.** Bumped the `extract_version_from_skill` fallback in `scripts/skills.py` from `0.0.0` → `0.0.1` so the manifest never reports `0.0.0` (which some tools treat as \"unset\"). Applies to skills that currently have no explicit `version:` in their SKILL.md frontmatter. Skills with an explicit version are unchanged. The change is sync-safe: when upstream a-d-k eventually adds version fields, those win; until then, the manifest reports the floor. 8. ~~**`installed_dir` for experimental skills.**~~ **All experimental skills install under a `-experimental` suffix.** Every experimental skill installs to `~/.claude/skills/<name>-experimental/` regardless of whether there's a stable skill with the colliding base name. Implemented in [databricks/cli#5243](databricks/cli#5243) via a new `SourceName` field on `SkillMeta`: the install-side manifest key (and install dir) carry the `-experimental` suffix; `SourceName` preserves the unsuffixed name for fetching from `experimental/<name>/` in this repo. Users see at a glance which installed skills are experimental. 9. ~~**Excluded a-d-k content.**~~ **Confirmed scope.** Excluded: `TEMPLATE/` (template, not a skill), `install_skills.sh` + `install_genie_code_skills.py` (a-d-k's installers — we use the cli installer instead), `databricks-builder-app/` (a Python app for a-d-k's builder UI), `databricks-mcp-server/` (the a-d-k MCP server — separate concern from skills), `databricks-tools-core/` (Python lib used by a-d-k tooling — no experimental skill references it), `hooks/hooks.json` (a-d-k plugin lifecycle hooks tied to `\${CLAUDE_PLUGIN_ROOT}/.claude-plugin/setup.sh`/`check_update.sh` — plugin-specific, not skill content), plus top-level repo metadata (`.github/`, `LICENSE.md`, `README.md`, `VERSION`, `install.{sh,ps1}`, etc.). Verified no experimental skill cross-references any excluded path. 10. ~~**README placement.**~~ **Verified.** `experimental/README.md` retains the adapted a-d-k skill list with a top warning block; the root `README.md` has an \"Experimental Skills\" section with an install-by-name example. Three concrete fixes applied during the verification pass: (a) dropped the stale `databricks-model-serving` collision example since that skill was removed from the PR, (b) install commands updated to include the `-experimental` suffix + flag per TODO #8's resolution, (c) added a short note in `experimental/README.md` explaining why the in-repo dir names don't carry the suffix (it's added at install time). 11. ~~**Manifest shape.**~~ **Resolved.** Replaced the original two-map design (top-level `skills` + `experimental_skills` plus per-skill `experimental` bool) with a single `skills` map where each entry's `repo_dir` field is the source of truth. Rationale: the directory location in the repo already determines status, so it's the natural single source. Consumers derive experimental state from `repo_dir` (see cli's `SkillMeta.IsExperimental`). The manifest generator (`scripts/skills.py`) raises a clear error if the same skill name appears under both `skills/` and `experimental/`, so future drift fails generation rather than silently overwriting. ## Test plan - [x] `python3 scripts/skills.py generate` regenerates the manifest cleanly. - [x] `python3 scripts/skills.py validate` passes. - [ ] CI green on this branch. - [ ] Manual: `databricks experimental aitools skills install` (no flag) installs only stable skills. - [ ] Manual: `databricks experimental aitools skills install --experimental` installs both. - [ ] Manual: `databricks experimental aitools skills install databricks-iceberg-experimental` errors because it's experimental. - [ ] Manual: `databricks experimental aitools skills install databricks-iceberg-experimental --experimental` installs that one skill. This pull request and its description were written by Claude.
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 free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Summary
Equivalent of #356 (which targets
main), adapted for theexperimentalbranch.databricks-apps-python/SKILL.md(renamed fromdatabricks-app-python/) now leads with AppKit (TypeScript + React SDK) as the recommended approach for new apps, with Python frameworks (Dash, Streamlit, Gradio, Flask, FastAPI, Reflex) demoted to an explicit alternative. Frontmatternameand H1 title updated to match.databricks-app-python→databricks-apps-python(plural) for the bundled skill directory, eval baselines, routing manifests, builder-app references, install scripts, and cross-skill mentions.databricks/databricks-agent-skills: bothinstall.shandinstall.ps1now fetch and install skills from databricks/databricks-agent-skills (databricks,databricks-apps,databricks-lakebase). Uses a single GitHub API tree call per install to fetch all files recursively, including nestedreferences/subdirectories.source:install-namerename syntax:AGENT_SKILLSsupportssource:install-nameentries (e.g.databricks-core:databricks) to decouple the upstream repo path from the local install directory name — no changes needed in the upstream repo.Differences vs #356 (preserves experimental's polish)
6-cli-approach.md(experimental's CLI-based app-lifecycle guide). Add AppKit support and databricks-agent-skills integration #356 still references6-mcp-approach.md.databricks-lakebase-autoscaleinstead ofdatabricks-lakebase-provisioned(which experimental removed).Test plan
bash install.sh --list-skillsshows agent skills with install names (notsource:install-nameraw entries)bash install.sh --skills-profile app-developerinstallsdatabricks-apps-python,databricks-app-apx, and agent skillsdatabricks,databricks-apps,databricks-lakebasebash install.sh --skills databrickscorrectly fetches and installsdatabricks-corefrom the agent-skills repo into a directory nameddatabricksbash install.sh --skills-profile allinstalls all 37 skills with no directory conflictsinstall.ps1on WindowsThis pull request was AI-assisted by Isaac.