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

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](../skills-watch.md) 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.

```bash
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:

```bash
databricks aitools update
```

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

```bash
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.

```text
/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.

```text
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.

```bash
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:

```text
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

- Databricks Agent Skills — https://github.com/databricks/databricks-agent-skills
- Databricks CLI authentication — https://learn.microsoft.com/azure/databricks/dev-tools/cli/authentication
- Databricks CLI authentication commands — https://learn.microsoft.com/azure/databricks/dev-tools/cli/reference/auth-commands
- Agent Skills specification — https://agentskills.io/specification