Customizing Databricks Assistant with Instructions

If you’ve ever told Databricks Assistant something like “use snake_case,” “prefer Plotly,” or “pull sales from catalog.schema.gold_sales” you’ve probably said it more than once. Repeating the same thing every session gets old fast.

This is where Databricks Assistant Instructions come in. Instead of reminding the Assistant every time, you set your preferences once and they carry into every conversation. It’s like handing the Assistant your style guide and domain notes upfront, so it just works the way you expect.

What are Instructions?

Instructions are short, reusable snippets that the Assistant automatically considers when responding. They help you with:

• Code conventions: such as naming, casing, and formatting. Many customers have specific code conventions they want to follow. Providing these conventions as instructions helps the Assistant generate code that matches your standards.
• Preferred libraries/frameworks: Help the Assistant choose the tools you prefer, so you don’t need to specify the library in new requests. Workspace admins can use this to recommend internal libraries or modules that should be used for specific tasks. e.g., “Use Plotly for charts”.
• Canonical data sources: The Assistant will help you recall where to find specific data, such as “Always use catalog.schema.gold_sales for sales data.” Workspace admins can also add useful onboarding resources for new users.
• Domain context: such as industry acronyms and internal terminology. Teach the Assistant about your domain so that it can understand your questions with minimal explanations.

Instructions in Action

Your instructions sit alongside your prompts so the Assistant can follow your guardrails without you repeating them. Let’s look at some examples.

If you want to use Plotly when generating visualizations, just type the following in the Assistant chat:

/addInstruction use plotly for visualization

The Assistant will then remember this instruction and automatically include it in every chat. Using the command /addInstruction, you can also tell the Assistant to do things like:

/addInstruction Keep chart colors in [your brand palette]
/addInstruction Use catalog.schema.gold_sales for sales data
/addInstruction Follow snake_casing for variable names
/addInstruction Recognize and use your domain-specific acronyms
/addInstruction Round all monetary values to two decimal places

With Instructions, the Assistant learns once and applies your guidance everywhere, reducing rework and helping you get to results faster.

Instruction Scopes

Some instructions may apply to all users in your workspace, whereas others are more relevant to you. To support this, the Assistant has two types of instructions:

1. User instructions: Save your preferences in `/Users/[email protected]/.assistant_instructions.md`. This is great for your personal coding style, tools, or shortcuts.
2. Workspace instructions: Admins can set shared instructions in `/Workspace/.assistant_workspace_instructions.md`. Perfect for org-wide conventions, onboarding resources, domain context, shared data sources or best practices.

Only the first 4,000 characters from each file are included in Assistant conversations. This ensures responses stay high-quality and focused.

How to Add Instructions

It is really easy to add instructions, so you can do it without losing your current context. There are two lightweight paths:

1. Tell the Assistant in chat. Type `/addInstruction` add your new instruction in the message, and the Assistant will save it instantly.
2. Edit the instructions markdown file: In the Assistant, click the Settings (gear) icon, create an instructions file, and edit it directly. This is useful for reviewing your existing instructions to ensure they are still relevant.

Databricks Assistant automatically picks up the instructions the next time you interact with it. Your instructions guide the Assistant’s responses, though they may not be applied perfectly in every case.

Tips for Writing Effective Instructions

We wanted to share a few tips that can help you get the most out of Assistant instructions:

• If you find yourself repeatedly correcting the Assistant about something, add that correction to your instructions.
• Write specific and crisp instructions.
• Curate your instructions file to stay under the 4,000-character limit.
• Use markdown headers and formatting to keep it organized and easy to read.

Treat your instructions like a knowledge and style guide. Small edits over time can help save you hours as the Assistant becomes more and more useful for your work.

Try Assistant Instructions Today

To get started, try with one instruction you always repeat—like your charting library or preferred variable style. From then on, the Databricks Assistant will start from your standards, not from scratch.

Please read our product documentation to learn more about Databricks Assistant Instructions. We’re excited to see how it streamlines your AI-assisted workflows.