Developer workflow and IaC

Use Databricks Agent Skills with Claude Code, Codex, and OpenCode

guidecuratedofficial evidenceall clouds4 min read

Databricks Agent Skills give a compatible coding agent product-specific instructions for Databricks work. Use them to improve task routing, command selection, authentication checks, and delivery practices. They do not add permissions or replace the Databricks CLI.

Use the current skill catalog to see which skills Databricks publishes. This guide explains how to install and use those skills without copying the changing catalog.

Choose one installation path#

Agent Recommended path Installed capability
Claude Code Databricks CLI or Claude plugin Skills; the plugin also adds commands and hooks
Codex Databricks CLI or Codex plugin Skills; the plugin also adds routing and context hooks
OpenCode Databricks CLI Skills in the detected OpenCode skill directory

Use one installation path for each agent. Two independently updated copies can give the agent conflicting instructions.

Databricks CLI#

Use the CLI path when you want the same stable skills across Claude Code, Codex, and OpenCode. It is the canonical installation path and supports individual or experimental skills.

databricks --version
databricks aitools install

The installer detects supported agents and writes the skills to their skill directories. Start a new agent session after installation. Update the installed skills with:

databricks aitools update

Install one stable skill when a team needs a smaller set:

databricks aitools install <skill-name>

Experimental skills do not have the same support and review level as stable skills. Add one only when the task needs it, and keep it separate from the production baseline.

Claude Code plugin#

The Claude Code plugin installs every stable skill. It also adds setup and health-check commands, prompt routing, session context, and an authentication failure hint.

/plugin marketplace add databricks/databricks-agent-skills
/plugin install databricks@databricks-agent-skills

Use /databricks:setup for guided authentication. Use /databricks:doctor for a read-only health check.

Codex plugin#

The Codex plugin installs every stable skill and adds prompt routing, session context, and an authentication failure hint.

codex plugin marketplace add databricks/databricks-agent-skills
codex plugin add databricks

Run /hooks after installation and after an update. Review and enable the pinned plugin hooks. Codex exposes the setup and health-check workflows through skills, not slash commands.

OpenCode#

Use the Databricks CLI path for OpenCode. The installer detects OpenCode and writes the stable skills to its supported skill directory. Start a new OpenCode session before you test discovery.

Configure authentication#

Use OAuth for an interactive user. The CLI manages the short-lived token and stores it in the operating system credential store when that store is available.

databricks auth login --host <workspace-url> --profile <profile-name>
databricks auth profiles

Use a service principal with OAuth for unattended work. Do not put a token, client secret, or other credential in a prompt, source file, or agent instruction.

Name the profile in the prompt and in each command. Do not let an agent silently select a default when more than one workspace or identity is available.

Route work to the correct skill#

Start with databricks-core for CLI, authentication, profile selection, and general routing. Then use the product skill that owns the task.

Task Skill to request
Find data or generate SQL databricks-data-discovery
Build or deploy a bundle databricks-dabs
Create or operate a job databricks-jobs
Build a Lakeflow pipeline databricks-pipelines
Govern Unity Catalog assets databricks-unity-catalog
Operate a serving endpoint databricks-model-serving
Evaluate a generative AI application databricks-mlflow-evaluation

Native agent discovery can select a skill from its description. Name the skill in the prompt when the task has a strict control boundary or when you must verify the route.

Give the agent four pieces of information:

  1. Name the Databricks profile and workspace.
  2. State the target resource or product.
  3. State the required result.
  4. State whether the agent can make changes or must stay read-only.

For example:

Use databricks-core and databricks-jobs with profile <profile-name>.
Inspect job <job-id> and explain its latest failure.
Do not change or run the job.

Verify the installation#

  1. Start a new agent session after installation or update.
  2. Ask the agent to use databricks-core and list the available profiles.
  3. Confirm that it shows the expected workspace URLs without credentials.
  4. Select one profile explicitly.
  5. Run one read-only task through the applicable product skill.
  6. Confirm that the agent names the target before it proposes a change.

If a skill is missing, run the installer again and review which agents it detected. If Codex routing does not start, review /hooks. If a command reaches the wrong workspace, stop and select the correct profile before you retry it.

Operating rules#

  • Start with read-only discovery. Approve a mutation only after the agent shows the exact target.
  • Keep development and production profiles distinct. Include the profile in every operational prompt.
  • Treat skill instructions as guidance, not authorization. Workspace and Unity Catalog permissions remain the control boundary.
  • Review generated code, plans, and deployment changes before execution.
  • Update the skills regularly. Check the generated catalog for new, removed, or renamed skills.

Official sources#

Referenced by