Extend the Assistant with agent skills

Create skills to extend Databricks Assistant in agent mode with specialized capabilities for your domain-specific tasks. This page explains how to create and optimize skills.

What are skills?

Create skills to extend the Assistant with specialized capabilities. Skills follow the open standard of Agent Skills. Skills package domain-specific knowledge and workflows that the Assistant can load when relevant to perform specific tasks. Skills can include guidance, best practices, reusable code, and executable scripts.

Skills should be tailored for domain-specific tasks. With skills, you can provide greater context (such as scripts, examples, and other resources) for a task than you can with instructions. Unlike custom instructions, which are applied globally, skills are loaded automatically and only in the relevant context. In agent mode, the Assistant automatically loads skills when relevant, based on your request and the skill’s description. This maintains an efficient context window and reduces the need to provide the same context across multiple chats.

note

Skills are only supported in Databricks Assistant agent mode.

Create a skill

To create a new skill:

1. In your user workspace folder, create a new skills folder. The folder path should be: /Users/{username}/.assistant/skills/.

   After creation, you can quickly access this folder in the Assistant panel. Click Settings, then click Open skills folder.

2. Create a SKILL.md file for your skill. Skills follow the specifications of Agent Skills.

3. Add the required frontmatter for your skill:

   ---
   name: skill-name
   description: A description of what this skill does and when to use it.
   ---

4. Add the skill instructions in Markdown format after the frontmatter. It’s recommended to include the following sections:

   • Step-by-step instructions: Clear procedural guidance
   • Examples: Sample inputs and expected outputs
   • Edge cases: Common variations and exceptions

5. (Optional) For more complex skills, you can provide and reference additional resources:

   • Scripts containing executable code that the agent can run.
   • Files containing additional documentation to reference, such as best practices and templates.

   When referencing other files, use relative paths from the root skill.

   For example, you might have a personal workflow skill that references ETL best practices, dashboard templates, and scripts for pipeline setup and deployment. Your skill’s folder could include the following files:

   /Users/{username}/.assistant/skills/
   ├── personal-workflows/
      ├── SKILL.md                # Workflow overview and best practices
      ├── etl-patterns.md         # Personal ETL best practices
      ├── dashboard-templates.md   # Reusable dashboard patterns
      └── scripts/
            ├── pipeline-setup.sh   # Environment setup scripts
            └── model-deploy.py     # Model deployment automation

Databricks Assistant automatically picks up your skills the next time you use it in agent mode.

Best practices

Follow these guidelines to write effective skills:

• Keep skills focused. Skills work best when they focus on a single task or workflow. Narrow scope makes it easier for the Assistant to recognize when a skill applies.
• Use clear names and descriptions. A concise, descriptive name and summary help the Assistant match the right skill to the right request.
• Be explicit and example-driven. Describe workflows step by step and include concrete examples or patterns the Assistant can reuse.
• Avoid unnecessary context. Only include information that is required for the task. Extra detail can make skills harder to apply reliably.
• Iterate over time. Treat skills as living workflows. Small updates based on real usage can significantly improve results.
• Separate guidance from automation. Use markdown to explain intent and best practices, and scripts for repeatable actions. Keeping these concerns distinct makes skills easier to maintain and reuse.