feat: add use-supervisor-api skill

[smurching]

Summary

• Adds a use-supervisor-api skill that guides users to build agents using the Databricks Supervisor API
• The skill covers: installing databricks-openai, declaring hosted tools (Genie spaces, UC functions, agent endpoints, MCP servers), updating agent_server/agent.py to call
  DatabricksOpenAI().responses.create(), granting resource permissions in databricks.yml, and beta limitations
• Skill is synced to all existing templates via sync-skills.py

What is the Supervisor API

The Supervisor API (POST https://{workspace_id}.ai-gateway.{domain}/mlflow/v1/responses) lets Databricks run the tool-selection and synthesis loop server-side. Users declare hosted
tools and call responses.create() — no agent loop code needed.

Currently in Beta — requires AI Gateway (Beta) preview enabled in the workspace.

Beta limitations noted in skill

• Usage tracking is not supported
• Cannot mix hosted tools with client-side function tools in the same request
• Inference parameters (e.g., temperature) are not supported when tools are passed

Test plan

• Skill appears in all template .claude/skills/ directories after running uv run python .scripts/sync-skills.py

[jennsun]

Will update these to correspond with the latest:

Here is the **complete, up-to-date list** of all tool types supported by the Supervisor API (`POST /api/2.0/mas/responses`), based on the current codebase:

## Allowlisted tool types (via `/responses` endpoint)

These are the tool types accepted by `_validate_responses_tool_types()` — the default allowlist in `_RESPONSES_DEFAULT_ALLOWED_TOOL_TYPES`:

| # | Tool type (as sent in `tools[].type`) | Description |
|---|---|---|
| 1 | **`genie_space`** | Genie AI/BI space — queries a Genie room by `space_id` |
| 2 | **`serving_endpoint`** | Serving endpoint (e.g., Knowledge Agent) — calls a model serving endpoint |
| 3 | **`unity_catalog_function`** | Unity Catalog function — executes a UC function by its 3-level path |
| 4 | **`external_mcp_server`** | External MCP server via UC connection — connects to an MCP server through a UC connection name |
| 5 | **`databricks_apps_mcp`** | Databricks Apps MCP — connects to an MCP server hosted as a Databricks App |
| 6 | **`code_interpreter`** | Code interpreter — executes Python code in a sandboxed REPL |

## Additional tool types (handled in code but not in the `/responses` allowlist by default)

These are processed by `_build_supervisor_conf_from_openai_format()` but are gated behind the `databricks.tiles.mas.enabledTools` Safe flag or used internally:

| # | Tool type | Description |
|---|---|---|
| 7 | **`function`** | Client-defined function tools (OpenAI-compatible) — always allowed, passed to the LLM as callable functions |
| 8 | **`agent`** | Sub-agent tool — delegates to another agent |
| 9 | **`vector_search`** | Vector search index — searches a Databricks vector search index (internal, stored in `request_context`) |
| 10 | **`iretriever`** | Instructed retriever — semantic document retrieval with knowledge sources (internal, stored in `request_context`) |

## Alias mapping

The codebase also accepts **alternative names** for some tool types via `_TOOL_TYPE_ALIASES`. These are Supervisor Agent naming conventions that map to the internal MAS names:

| Alias (what you can send) | Maps to internally |
|---|---|
| `genie_space` | `genie` |
| `serving_endpoint` | `agent_endpoint` |
| `unity_catalog_function` | `uc_function` |
| `external_mcp_server` | `mcp` |
| `databricks_apps_mcp` | `mcp` |

So for example, sending `type: "genie_space"` or `type: "genie"` both work — the alias is resolved before processing.

## Connector shorthands (sub-type of `external_mcp_server` / `mcp`)

When using `external_mcp_server` or `mcp` tool type, you can specify a `connector` shorthand instead of a `connection_name`. These auto-create system-managed UC connections:

| Connector shorthand | Service | Has built-in MCP server? |
|---|---|---|
| `google_drive` | Google Drive | Yes (uses internal MAS adapter) |
| `sharepoint` | SharePoint | Yes (uses internal MAS adapter) |
| `github_mcp` | GitHub | No (uses external MCP proxy) |
| `atlassian_mcp` | Atlassian (Jira/Confluence) | No (uses external MCP proxy) |

---

So your table should be updated to:

| Tool type | Resource to grant |
|-----------|-------------------|
| `genie_space` | `genie_space` with `CAN_RUN` |
| `unity_catalog_function` | `uc_securable` (FUNCTION) with `EXECUTE` |
| `serving_endpoint` | `serving_endpoint` with `CAN_QUERY` (KA endpoints only) |
| `external_mcp_server` | `uc_securable` (CONNECTION) with `USE_CONNECTION` |
| `databricks_apps_mcp` | *(Databricks App access)* |
| `code_interpreter` | *(no external resource — sandboxed REPL)* |
| `function` | *(client-side — no server resource)* |
| `agent` | *(sub-agent delegation)* |
| `vector_search` | *(vector search index access)* |
| `iretriever` | *(instructed retriever — knowledge sources)* |

[jennsun]

taking over this pr: #183