Improve skills based on CAO benchmark run 2 findings (#89)

## Summary

Addresses 4 friction clusters identified in the CAO (Coding Agent
Optimization) benchmark run 2 (May 21-22, 2026; Opus 4.7 + Codex 5.5, 25
tasks).

### Changes

**P2: OAuth auth guidance (Cluster A -- 16/25 tasks affected)**
- `databricks-core/SKILL.md`: Add troubleshooting row for `"OAuth Token
not supported for current auth type pat"` directing to `databricks auth
login`
- `databricks-apps/SKILL.md`: Note that `databricks apps logs` requires
OAuth in Post-Deploy Verification

**P4: Model Serving endpoint readiness (Cluster F -- regression on both
models)**
- `databricks-model-serving/SKILL.md`: Add "Endpoint Readiness"
subsection with state transitions, provisioning times, and
poll-before-query guidance. Enhance troubleshooting for `NOT_READY`
state.

**P5: Off-platform anti-pattern (Drizzle task -- Codex scores 35)**
- `databricks-lakebase/references/off-platform.md`: Add callout that
off-platform apps are NOT Databricks Apps. Add "Running Locally" section
with standard Node.js commands.
- `databricks-lakebase/SKILL.md`: Strengthen off-platform reference
description.

**P6: Lakehouse Sync UI-only limitation (Cluster G)**
- `databricks-lakebase/references/lakehouse-sync.md`: Strengthen
warning: "Do NOT attempt to automate this step."
- `databricks-lakebase/SKILL.md`: Add "(UI-only)" annotation to
Lakehouse Sync reference entry.

### Context

The benchmark also identified these clusters that are addressed
elsewhere:
- **Cluster B/D** (npm proxy ETIMEDOUT / apps init failure): Fixed in
newer AppKit version (wrong `package-lock.json` entry)
- **Cluster C** (CLI `experimental aitools install` deprecation):
Addressed in PR #60

### Test plan

- [x] `python3 scripts/skills.py validate` passes

This pull request and its description were written by Isaac.

Author: pkosiec

.github/CODEOWNERS

@@ -1,6 +1,6 @@
 * @lennartkats-db @simonfaltum @databricks/eng-apps-devex
 /skills/ @lennartkats-db @simonfaltum # net-new skills must be approved by @lennartkats-db
-/skills/databricks/ @lennartkats-db @simonfaltum @camielstee-db @databricks/eng-apps-devex
+/skills/databricks-core/ @lennartkats-db @simonfaltum @camielstee-db @databricks/eng-apps-devex
 /skills/databricks-apps/ @databricks/eng-apps-devex
 /skills/databricks-lakebase/ @databricks/eng-apps-devex
 /skills/databricks-model-serving/ @databricks/eng-apps-devex

skills/databricks-apps/SKILL.md

@@ -222,3 +222,5 @@ After deploying, verify the app is running:
 databricks apps get <app-name> --profile <PROFILE> -o json   # Check app_status.state: RUNNING
 databricks apps logs <app-name> --follow --profile <PROFILE>  # Stream live logs (Ctrl+C to stop)
 ```
+
+> **Note:** `databricks apps logs` requires OAuth authentication and does not work with PAT. Use `databricks apps get` for status checks if using PAT auth.

skills/databricks-core/SKILL.md

@@ -123,6 +123,7 @@ databricks bundle run <RESOURCE> -t <TARGET> --profile <PROFILE>
 | Error | Solution |
 |-------|----------|
 | `cannot configure default credentials` | Use `--profile` flag or authenticate first |
+| `configuration does not support OAuth tokens` | The command requires OAuth (e.g., `databricks apps logs`). Re-authenticate with `databricks auth login --host <URL> --profile <PROFILE>`. See [CLI Authentication](databricks-cli-auth.md). |
 | `PERMISSION_DENIED` | Check workspace/UC permissions |
 | `RESOURCE_DOES_NOT_EXIST` | Verify resource name/id and profile |
 

skills/databricks-lakebase/SKILL.md

@@ -33,9 +33,9 @@ Lakebase is Databricks' serverless Postgres-compatible database, available on bo
 - [computes-and-scaling.md](references/computes-and-scaling.md) — Sizing, endpoint management, scale-to-zero, HA
 - [connectivity.md](references/connectivity.md) — Connection patterns, token refresh, Data API
 - [synced-tables.md](references/synced-tables.md) — Lakebase synced tables, data type mapping, capacity planning
-- [lakehouse-sync.md](references/lakehouse-sync.md) — CDC from Lakebase Postgres to Unity Catalog Delta tables
+- [lakehouse-sync.md](references/lakehouse-sync.md) — CDC from Lakebase Postgres to Unity Catalog Delta tables (**UI-only** — cannot be configured via CLI or API)
 - [pgvector.md](references/pgvector.md) — Vector similarity search with pgvector extension
-- [off-platform.md](references/off-platform.md) — Off-platform Lakebase: env management, token refresh, Drizzle ORM
+- [off-platform.md](references/off-platform.md) — Off-platform Lakebase (NOT Databricks Apps): external Node.js apps connecting via `@databricks/lakebase`, env management, token refresh, Drizzle ORM
 
 ## Resource Hierarchy
 

skills/databricks-lakebase/references/lakehouse-sync.md

@@ -31,7 +31,7 @@ Each row includes CDC metadata columns:
 
 ## Enablement
 
-**Lakehouse Sync is UI-only** — configured via the "Lakehouse sync" tab in the branch overview, not via CLI or API. It operates at the **schema level**: once enabled, all current and future tables in that schema sync to Unity Catalog.
+**Lakehouse Sync is UI-only — there is NO CLI command or REST API to configure it. Do NOT attempt to automate this step.** It is configured through the Databricks workspace UI: "Lakehouse sync" tab in the branch overview. It operates at the **schema level**: once enabled, all current and future tables in that schema sync to Unity Catalog.
 
 Navigate to: **Catalog** → your Autoscaling project → branch → **Lakehouse Sync** → **Start Sync**, then select the source database/schema, destination catalog/schema, and tables.
 

skills/databricks-lakebase/references/off-platform.md

@@ -1,5 +1,7 @@
 # Off-Platform Lakebase: Connecting from External Apps
 
+> **Off-platform apps are NOT Databricks Apps.** Do NOT use `databricks apps init`, `databricks apps deploy`, `app.yaml`, or any Databricks Apps platform commands. Off-platform apps run on your own infrastructure (Vercel, AWS, local Node.js, etc.) and use standard Node.js tooling (`npm run dev`, `node server.js`).
+
 Connect to Lakebase from apps deployed outside Databricks App Platform (e.g. Vercel, AWS, Netlify, or any Node.js server).
 
 ## Recommended: `@databricks/lakebase` Package

skills/databricks-model-serving/SKILL.md

@@ -82,6 +82,19 @@ databricks serving-endpoints create <ENDPOINT_NAME> \
   ```
 - For provisioned throughput or custom model endpoints, run `databricks serving-endpoints create -h` to discover the required JSON fields for your endpoint type.
 
+### Endpoint Readiness
+
+After `create` or `update-config`, the endpoint provisions compute and loads the model. **Do not query the endpoint until it is ready.**
+
+Poll for readiness:
+
+```bash
+databricks serving-endpoints get <ENDPOINT_NAME> --profile <PROFILE> -o json
+# Ready when: state.ready == "READY" AND state.config_update == "NOT_UPDATING"
+```
+
+Provisioning may take several minutes. Provisioned throughput endpoints take the longest (GPU allocation). Queries to endpoints that are not yet `READY` return 404 or 503 errors.
+
 ## Query an Endpoint
 
 ```bash
@@ -170,7 +183,7 @@ Then add a tRPC route to call it from your app. For the full app integration pat
 |-------|----------|
 | `cannot configure default credentials` | Use `--profile` flag or authenticate first |
 | `PERMISSION_DENIED` | Check workspace permissions; for apps, ensure `serving_endpoint` resource declared with `CAN_QUERY` |
-| Endpoint stuck in `NOT_READY` | Check `build-logs` for the served model (get entity name from `get` output) |
+| Endpoint stuck in `NOT_READY` | Wait up to 30 min for provisioned throughput. Check build logs: `build-logs <NAME> <ENTITY_NAME>` (get entity name from `get` output → `served_entities[].name`) |
 | `RESOURCE_DOES_NOT_EXIST` | Verify endpoint name with `list` |
 | Query returns 404 | Endpoint may still be provisioning; check `state.ready` via `get` |
 | `RATE_LIMIT_EXCEEDED` (429) | AI Gateway rate limit; check `put-ai-gateway` config or retry after backoff |