Fix skill inconsistencies and add required reading sections#5
Merged
Conversation
- fix positional args in UC commands (schemas/tables/volumes list) - fix daysAgo helper to return string for sql.date() - fix PieChart props (uses xKey/yKey, not nameKey/valueKey) - fix import paths and add missing imports - move memoization warning earlier in appkit-sdk.md - remove deprecated aitools validate command - add "Required Reading by Phase" tables to encourage reading refs - remove duplicate scaffold command from overview.md
7 tasks
jamesbroadhead
added a commit
that referenced
this pull request
May 12, 2026
Replaces the previous import (a-d-k commit 2228c3e on add_appkit) with the head of a-d-k PR #533 (commit 9c7a5b3 on appkit-on-experimental), which targets a-d-k's experimental branch. Changes: - Refresh 23 experimental skill directories from the new source. - Drop databricks-lakebase-provisioned — removed on a-d-k experimental. - databricks-apps-python: rename + SKILL.md now leads with AppKit (TypeScript + React SDK) and demotes Python frameworks to alternatives; 6-mcp-approach.md replaced with 6-cli-approach.md. - databricks-lakebase-autoscale/references/connection-patterns.md: change placeholder `user:password` to `<user>:<password>` so the secret scanner doesn't flag the doc-only example. Cosmetic only. - Continue to exclude databricks-model-serving and databricks-spark-declarative-pipelines (PR #73 TODOs #1b and #5). - Regenerate manifest.json and agents/openai.yaml stubs via scripts/skills.py generate. - Update experimental/README.md provenance section with the new SHA, branch, and divergence notes. Co-authored-by: Isaac
jamesbroadhead
added a commit
that referenced
this pull request
May 15, 2026
Replaces the previous import (a-d-k commit 2228c3e on add_appkit) with the head of a-d-k PR #533 (commit 9c7a5b3 on appkit-on-experimental), which targets a-d-k's experimental branch. Changes: - Refresh 23 experimental skill directories from the new source. - Drop databricks-lakebase-provisioned — removed on a-d-k experimental. - databricks-apps-python: rename + SKILL.md now leads with AppKit (TypeScript + React SDK) and demotes Python frameworks to alternatives; 6-mcp-approach.md replaced with 6-cli-approach.md. - databricks-lakebase-autoscale/references/connection-patterns.md: change placeholder `user:password` to `<user>:<password>` so the secret scanner doesn't flag the doc-only example. Cosmetic only. - Continue to exclude databricks-model-serving and databricks-spark-declarative-pipelines (PR #73 TODOs #1b and #5). - Regenerate manifest.json and agents/openai.yaml stubs via scripts/skills.py generate. - Update experimental/README.md provenance section with the new SHA, branch, and divergence notes. Co-authored-by: Isaac
jamesbroadhead
added a commit
that referenced
this pull request
May 15, 2026
User-walkthrough testing of experimental/README.md surfaced 13 broken cross-reference links in 9 SKILL.md files, all in "Related Skills" sections. Each pointed at ../<name>/SKILL.md for a skill that doesn't exist in experimental/ — they reference earlier-resolved name collisions (databricks-jobs, databricks-model-serving) or experimental-only content that was excluded from this import (databricks-spark-declarative-pipelines). Replacement strategy mirrors c4daa14: use the bare skill name without a link, matching the convention stable skills use in their own cross-references. Targets: - databricks-spark-declarative-pipelines (excluded per TODO #5) → databricks-pipelines (stable analogue) - databricks-model-serving (dropped per TODO #1b) → databricks-model-serving (bare; stable exists at same name) - databricks-jobs (merged per TODO #1a) → databricks-jobs (bare; stable exists at same name) Also rewrites the stale "collision handling for jobs and model-serving" sentence in experimental/README.md — those collisions were resolved via merge + drop respectively in this PR, not via the suffix mechanism the sentence implied. Co-authored-by: Isaac
lennartkats-db
pushed a commit
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.
4 tasks
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
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.
No description provided.