experimental: README updates for -experimental install suffix

- experimental/README.md: install examples now use the -experimental
  suffix on the skill name + the --experimental flag (matching the
  install-path behaviour landed in databricks/cli#5243). Adds a short
  note explaining why the in-repo dir name and the install dir name
  differ.
- experimental/README.md: drop databricks-model-serving from the
  collision example (it was removed from this PR earlier).
- experimental/README.md: update the (also available as stable skill)
  note for databricks-jobs to point at the open TODO #1a.
- Root README: clarify the suffixed install name in the by-name install
  example.

Co-authored-by: Isaac

Author: jamesbroadhead

README.md

@@ -36,8 +36,9 @@ on a **best-effort basis**.
   do not follow the same review / quality bar as the stable skills under
   [`skills/`](./skills/).
 - They are **not installed by default** by `databricks experimental aitools
-  skills install`. Pass `--experimental` to install all of them, or install a
-  specific one by name.
+  skills install`. Pass `--experimental` to install all of them, or install
+  a specific one by name (with the `-experimental` suffix and the flag —
+  e.g. `databricks-iceberg-experimental --experimental`).
 - See [`experimental/README.md`](./experimental/README.md) for the full list
   and caveats.
 

experimental/README.md

@@ -8,8 +8,9 @@
 > - They do not follow the same review / quality bar as the skills in
 >   [`../skills/`](../skills/).
 > - They may be out of date relative to upstream `ai-dev-kit`.
-> - They may overlap or conflict with the stable skills (e.g.
->   `databricks-jobs`, `databricks-model-serving` exist in both directories).
+> - They may overlap with stable skills (e.g. `databricks-jobs` exists in
+>   both directories — see the install-path note below for how that's
+>   resolved on disk).
 > - They are not installed by `databricks experimental aitools skills install`
 >   by default — you have to opt in (see the root README).
 >
@@ -30,10 +31,15 @@ These experimental skills are **not** installed by default. To install them via
 # Install all experimental skills at once
 databricks experimental aitools skills install --experimental
 
-# Install a single experimental skill by name
-databricks experimental aitools skills install databricks-iceberg
+# Install a single experimental skill by name (note the -experimental suffix)
+databricks experimental aitools skills install databricks-iceberg-experimental --experimental
 ```
 
+The names in this directory don't carry the `-experimental` suffix — that's
+added at install time so the on-disk skills directory unambiguously
+distinguishes experimental from stable. e.g. `databricks-iceberg` in this
+repo installs to `~/.claude/skills/databricks-iceberg-experimental/`.
+
 See the root [README](../README.md) for details on the stable install path.
 
 ## Available Skills
@@ -55,7 +61,7 @@ See the root [README](../README.md) for details on the stable install path.
 - **databricks-dbsql** - Databricks SQL warehouse patterns
 - **databricks-iceberg** - Apache Iceberg tables (Managed/Foreign), UniForm, Iceberg REST Catalog, Iceberg Clients Interoperability
 - **databricks-spark-structured-streaming** - Spark Structured Streaming patterns
-- **databricks-jobs** - Multi-task workflows, triggers, schedules *(also available as stable skill)*
+- **databricks-jobs** - Multi-task workflows, triggers, schedules *(also available as a stable skill — see TODO #1a in PR #73)*
 - **databricks-synthetic-data-gen** - Realistic test data with Faker
 - **databricks-zerobus-ingest** - Zerobus ingest patterns
 - **spark-python-data-source** - Python data sources for Spark

manifest.json

@@ -1,6 +1,6 @@
 {
   "version": "2",
-  "updated_at": "2026-05-12T17:00:36Z",
+  "updated_at": "2026-05-12T20:19:43Z",
   "skills": {
     "databricks-apps": {
       "version": "0.1.1",