Dremio Agent Skill

This repository contains a specialized "Agent Skill" for Dremio. It teaches AI coding assistants (like Cursor, Claude Code, or Antigravity) how to interact with Dremio's Data Lakehouse platform.

What's Included?

The skill is located in the dremio-skill/ directory and includes:

• SKILL.md: The main entry point defining the skill's capabilities.
• knowledge/: Comprehensive documentation for:
  • Dremio CLI: Command-line administration.
  • Python SDK (dremioframe): Scripting and automation.
  • SQL: Query syntax, Iceberg DML, and metadata functions.
  • REST API: Low-level API endpoints.
• rules/: Configuration files like .cursorrules to load this context into your AI session.

Installation

We provide automated scripts to install the skill globally (for all projects) or locally (per project).

Mac / Linux

Run the interactive installer:

./install.sh

Windows (PowerShell)

Run the interactive installer:

./install.ps1

Installation Modes

The installer will ask you to choose a mode:

1. Global Install (Symlink):

   • Best for: Developers who want this skill available everywhere.
   • What it does: Symlinks this repository to your global ~/.agent/skills (Antigravity) and ~/.claude/skills (Claude Code).
   • Benefit: Any updates you pull to this repo are immediately reflected in your AI tools.

2. Local Project Install (Copy):

   • Best for: Sharing the skill within a specific team repository.
   • What it does:
     • Copies the dremio-skill folder to your target project.
     • Installs .cursorrules to the project root.
     • Configures hidden .agent and .claude symlinks so the tools auto-detect the local copy.
   • Benefit: The skill travels with the project repo, ensuring all team members have the same context.

Manual Setup (If preferred)

If you prefer to manually configure the skill:

1. Copy dremio-skill/ to your project root.
2. Copy dremio-skill/rules/.cursorrules to your project root .cursorrules.

🔐 Credentials & Configuration

To effectively use this skill, you must securely configure your Dremio credentials. Never paste secrets directly into your prompt.

1. Python (dremioframe)

DremioFrame scripts generated by the AI will expect credentials in environment variables or a .env file.

rename the template.env file in this repo to .env

1. Create a .env file in your project root:

    # --- Dremio Cloud Configuration ---
# The primary endpoint for Dremio Cloud REST API
DREMIO_ENDPOINT="https://api.dremio.cloud"

# Your Personal Access Token (Settings > User Settings > Personal Access Tokens)
DREMIO_PAT="your-dremio-cloud-pat"

# Your Project ID (Found in the URL or Project Settings)
DREMIO_PROJECT_ID="your-project-id-uuid"

# --- Dremio Software Configuration (v26+ Recommended) ---
# The URL of your Dremio coordinator
DREMIO_SOFTWARE_HOST="https://dremio.company.com"

# Personal Access Token for Software (Preferred over user/pass)
DREMIO_SOFTWARE_PAT="your-software-pat"

# Enable TLS (True/False) - usually True for production
DREMIO_SOFTWARE_TLS="true"

# Iceberg Catalog URI (Required for PyIceberg/Dremio Software)
# Default is often: https://catalog.dremio.cloud/api/iceberg
DREMIO_ICEBERG_URI="https://catalog.dremio.cloud/api/iceberg"

# --- Dremio Software (Legacy/Alternative Auth) ---
# Username and Password can be used if PAT is not available (v25 or older)
# DREMIO_SOFTWARE_USER="admin"
# DREMIO_SOFTWARE_PASSWORD="your-password"

2. The AI knows to use os.getenv() to retrieve these values securely.

2. Dremio CLI

There are currently two CLIs available. Choose the one that suits your environment:

A. Official Dremio CLI (Cloud Only)

Can be installed with pipx install dremio-cli or pip install dremio-cli. It reads credentials from environment variables (DREMIO_TOKEN, DREMIO_PROJECT_ID) or ~/.config/dremioai/config.yaml. The AI can use commands like dremio folder list directly.

B. Community Dremio CLI (Cloud & Software)

Installed with pip install alt-dremio-cli (Code repo: https://github.com/developer-advocacy-dremio/dremio-python-cli). Credential management is handled via profiles stored in ~/.dremio/profiles.yaml.

Run the following command in your terminal to create a profile (do this before asking the AI to run Community CLI commands):

# For Dremio Cloud
alt-dremio-cli profile create cloud-profile \
  --base-url https://api.dremio.cloud/v0 \
  --token "your-pat" \
  --project-id "your-project-id"

# For Dremio Software (v26+ with PAT is recommended)
alt-dremio-cli profile create software-profile \
  --base-url https://dremio.company.com \
  --token "your-software-pat"

Once configured, the AI can run commands like alt-dremio-cli --profile cloud-profile ....

🛠️ Tool Compatibility

This skill is designed for Agentic Coding Tools that support the SKILL.md standard or context loading via .cursorrules.

• Google Antigravity: Fully supported. Discoverable via SKILL.md. (You may want to start a new chat asking Antigravity to scan for available skills)
• Claude Code: Supported in latest versions via dremio-skill/SKILL.md or .clauderc.
• Cursor / VS Code: Supported by copying dremio-skill/rules/.cursorrules to your project root.
• Other Agents: Any agent that can read Markdown documentation in the dremio-skill/knowledge folder, just tell them to read the /dremio-skill/SKILL.md file.

🗣️ Example Prompts

Try these prompts to leverage the full power of the Dremio Skill:

🐍 Python Automation (DremioFrame)

• "Write a Python script to list all sources and their metadata policies."
• "Create a script to clone a space 'Marketing' into a new space 'Marketing_Backup'."
• "Write a script that uses the Dremio Lineage API to find all tables downstream of 'Sales.Transactions'."
• "Generate a script to create 50 users from a CSV file using the Admin API."

💻 CLI Operations

• "Give me the CLI command to export the entire 'Finance' space to a JSON file."
• "How do I use the CLI to promote a folder to a physical dataset?"
• "Write a bash script using dremio-cli to refresh all reflections in the 'Datalake' source."

📊 SQL & Analysis

• "Write a Dremio SQL query to optimize the 'Sales.Events' Iceberg table."
• "How do I query the Iceberg metadata to see how many snapshots the table 'Logs' has?"
• "Write a query to PIVOT the 'MonthlySales' table so that months become columns."

❓ Troubleshooting

The AI doesn't know about Dremio

• Check Context: Ensure the dremio-skill folder is in your project root.
• Cursor Users: Verify .cursorrules exists in the root and you are in "Agent" or "Composer" mode (not just "Chat").
• Antigravity: Ensure you are in a session where the skill has been loaded/indexed.

Authentication Errors in Scripts

• Check .env: Make sure your .env file exists and has the correct variable names (DREMIO_PAT, DREMIO_ENDPOINT, etc.).
• Load .env: Ensure the generated Python script includes from dotenv import load_dotenv; load_dotenv(). Remind the AI to include this if it forgets.
• Software vs Cloud: Double-check you aren't using a Cloud endpoint with Software credentials or vice-versa.

"Command Not Found" (CLI)

• Install CLI: Did you run pip install dremio-cli?
• Profile: Did you create a profile using dremio profile create? The AI usually assumes a profile exists.

🤖 Agent Best Practices

To ensure the AI deterministically uses this skill, follow these rules:

1. For Coding Tools that Don't support skills (OpenCode, etc.)

If you are using a web-based chat interface that doesn't support automatic context loading:

1. copy the .cursorrules and AGENTS.MD files in the dremio-skill/rules to the root of the repo or copy their contents to your existing .cursorrules or AGENTS.md
2. Tell the agent to read the .cursorrules and AGENTS.md files in the first message and periodically throughout the conversation.
3. This "primes" the model with the role, rules, and syntax preferences defined in the skill.

2. For Coding Assistants (Cursor, VS Code)

Ensure the .cursorrules file is present in your project root.

• Explicit Activation: If the agent seems lost, type: "@rules Read the Dremio Skill documentation in dremio-skill/SKILL.md before answering."
• File References: When asking about specific features, reference the knowledge file if you know it (e.g., "How do I do this using dremioframe? Check knowledge/python/tree.md").

3. General "Golden Rules"

• Be Specific: Instead of "Make a script", say "Make a dremioframe script to..."
• Correction: If the AI hallucinates a function (like query_to_pandas), correct it: "That method doesn't exist. Check knowledge/python/tree.md for the correct client.query() syntax."

4. For online chat interfaces

• Tell the agent to learn the dremio skill by reading the online repo https://github.com/developer-advocacy-dremio/dremio-agent-skill and and to start with the SKILL.md file at https://github.com/developer-advocacy-dremio/dremio-agent-skill/blob/main/dremio-skill/SKILL.md