Skip to main content

Extend Genie Code with agent skills

Genie Code ships with built-in skills for common Databricks workflows: writing code in notebooks, exploring data in Unity Catalog, building dashboards, creating pipelines, and working with MLflow. Create custom skills to extend Genie Code with specialized capabilities for your team's domain-specific tasks.

What are Genie Code skills?​

Create skills to extend Genie Code with specialized capabilities. Skills follow the open standard of Agent Skills. Skills package domain-specific knowledge and workflows that Genie Code 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. Genie Code automatically loads skills when relevant, based on your request and the skill’s description. You can also manually invoke skills by @ mentioning them. This maintains an efficient context window and reduces the need to provide the same context across multiple chats.

There are two types of skills:

  • Workspace skills: Available to everyone in the workspace. Workspace administrators can create workspace skills and grant others access to the skills folder to add more. Use workspace skills to enforce organization-wide standards, deliver consistent output across users (for example, a PII-handling skill that masks sensitive columns), or serve different teams (for example, pipeline templates for data engineers and model training playbooks for ML platform users).
  • User skills: Available only to you. Use user skills for personal preferences such as preferred libraries, coding style, or role and background context. User skills are also useful for prototyping a skill before promoting it to the workspace level.

Create a skill​

You can create a skill with Genie Code, upload skill folders from your computer, or create the skill files manually.

In Genie Code, click Customizations, then select Skills to open the skills list. Click New to see the available options.

If you're a workspace administrator, the New menu has two sections:

  • For everyone in this workspace: Create or upload workspace skills that are available to everyone in the workspace.
  • Just for me: Create or upload personal skills, or add skills from an existing workspace folder.

Other users see the personal skill options without the section headings.

Create with Genie​

To create a skill in a chat:

  1. In the skills list, click New, then select Create with Genie. If you're a workspace administrator, select the option under the heading for your intended audience.
  2. In the new chat, describe the skill you want Genie Code to create.

The new skill appears in your skills list. Personal skills are saved in your workspace home folder at /Users/{username}/.assistant/skills/. Workspace skills are saved to /Workspace/.assistant/skills/ and are turned on for everyone in the workspace.

Upload skills from your computer​

If you already have skill folders on your computer, upload them from the skills list. Each skill folder must contain a SKILL.md file and follow the Agent Skills specification.

  1. Click New, then select Upload from computer. If you're a workspace administrator, select the option under For everyone in this workspace or Just for me.
  2. Drag your skill folders into the upload dialog, or click Browse folders to select them.
  3. Review the skills to upload, then click Upload for personal skills or Upload to workspace for workspace skills.

Uploaded skills appear in your skills list. Personal uploads are saved in your workspace home folder at /Users/{username}/.assistant/skills/. Workspace uploads are saved to /Workspace/.assistant/skills/ and are turned on for everyone in the workspace.

Uploading a workspace skill with the same name as an existing workspace skill replaces it for everyone in the workspace.

Create skill files manually​

By default, skills are in the .assistant/skills/ folder. Each skill must have its own folder and a SKILL.md file within that folder. The location depends on the skill type:

  • Workspace skills: Workspace/.assistant/skills/
  • User skills: /Users/{username}/.assistant/skills/

To create a skill manually:

  1. Create the skills folder at the appropriate path for your skill type if it doesn't exist.

  2. Create a dedicated folder for your skill inside the skills folder. Each skill must have its own folder. For example:

    Workspace/.assistant/skills/
    └── ml-workflows/
    └── SKILL.md

    /Users/{username}/.assistant/skills/
    └── personal-workflows/
    └── SKILL.md
  3. Inside your skill folder, create a SKILL.md file. This file is required and defines the skill. Skills follow the specifications of Agent Skills.

  4. Add the required frontmatter for your skill:

    YAML
    ---
    name: skill-name
    description: A description of what this skill does and when to use it.
    ---
  5. 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
  6. (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, a workspace machine learning workflow skill and a personal workflow skill might have the following structure:

    Workspace/.assistant/skills/
    ├── ml-workflows/
    ├── SKILL.md # Workflow overview and best practices
    ├── training-patterns.md # Standard ML training patterns
    └── scripts/
    └── model-deploy.py # Model deployment automation

    /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

Genie Code automatically picks up your skills the next time you use it. You can also @ mention skills to ensure Genie Code uses them.

When you edit an existing skill, start a new chat to apply your changes. Edits don't take effect in active chats. If a skill still appears stale, such as showing old behavior or an outdated description, hard-refresh the browser tab to clear cached skill metadata.

Add skills from another folder​

By default, Genie Code loads skills from the .assistant/skills/ folders. You can also register additional skill folders, so that skills stored elsewhere in your workspace are available without moving them into .assistant/skills/. This is useful when you keep skills in a Databricks Git folder next to the project code they relate to.

The folder you register must be a parent folder that contains skill subfolders, the same structure as .assistant/skills/. Each skill still needs its own subfolder with a SKILL.md file. Don't register a folder that contains a SKILL.md file directly.

For example, register /Users/{username}/my-skills/ when it has the following structure:

/Users/{username}/my-skills/
├── etl-checks/
│ └── SKILL.md
└── release-notes/
└── SKILL.md

To register an extra skill folder:

  1. In Genie Code, click Customizations, then select Skills.
  2. Click New, then select Add from workspace folder. If you're a workspace administrator, this option is under Just for me.
  3. In the workspace browser, select the parent folder that contains your skill subfolders. You need read access to the folder.

Skills from the registered folder appear in your skills list alongside your default skills. Registering a folder adds its skills for you, not for everyone in the workspace. Your default .assistant/skills/ folders remain available.

After you register a folder, click Folders in the skills list to view your registered folders. In the Skill folders dialog, click Add folder to register another folder, or remove a folder from the list to stop loading its skills. Removing a folder from this list doesn't delete the folder or its files.

Best practices for writing skills​

Follow these guidelines to write effective skills:

  • Choose the appropriate skill type. Use workspace skills to codify shared standards (such as PII handling, naming conventions, or team-specific templates) so every user gets consistent output. Use user skills for personal preferences and to prototype a skill before promoting it to the workspace.
  • Keep skills focused. Skills work best when they focus on a single task or workflow. Narrow scope makes it easier for Genie Code to recognize when a skill applies.
  • Use clear names and descriptions. A concise, descriptive name and summary help Genie Code match the right skill to the right request.
  • Be explicit and example-driven. Describe workflows step by step and include concrete examples or patterns Genie Code 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.
  • Author skills with Genie Code. Use Genie Code to draft and refine skills. Test new or updated skills on representative tasks to find where the agent struggles, then update the instructions to close those gaps.
  • 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.
  • Version control your skills. Back your skills folder with Databricks Git folders to track changes, collaborate with teammates, and roll back when needed. You can keep that folder anywhere in your workspace and register it as an extra skill folder, so you don't have to clone it into .assistant/skills/.

Additional resources​