Skip to main content

Quickstart for AI agents

Get started with Bauplan using AI coding assistants like Claude Code, GitHub Copilot, or Cursor. This guide shows you how to work with your lakehouse conversationally, using natural language to explore data, load files, and build pipelines.

In this Quick start, you'll use an AI agent to:

  • Explore tables and schemas in your lakehouse
  • Run queries and profile your data
  • Safely ingest data from S3 using the Write-Audit-Publish pattern
  • Build and run a transformation pipeline

Prerequisite​

  • An AI agent (Claude Code) that can run terminal commands.
  • Python 3.10 or above.

For installation steps, follow the Installation guide.

Setup Your Repository​

To work effectively with AI agents, you need to provide them with Bauplan-specific guidance, command references, and specialized workflows. These files teach your AI assistant how to work with Bauplan's CLI, SDK, and best practices—enabling it to write correct code, follow safety rules, and use proven patterns for common tasks like data ingestion and pipeline creation.

To create the folder structure and fetch all the files you need to run this quick start, run this in your terminal:

# Create directory structure
mkdir -p .claude/bauplan-reference
mkdir -p .claude/skills/creating-bauplan-pipelines
mkdir -p .claude/skills/wap-ingestion
mkdir -p .claude/skills/explore-data

# Download Claude.md and skills into your local repo
curl -o .claude/CLAUDE.md https://raw.githubusercontent.com/BauplanLabs/bauplan-mcp-server/main/CLAUDE.md
curl -o .claude/bauplan-reference/bauplan_cli.md https://raw.githubusercontent.com/BauplanLabs/bauplan-mcp-server/main/bauplan_reference/cli.md
curl -o .claude/skills/creating-bauplan-pipelines/SKILL.md https://raw.githubusercontent.com/BauplanLabs/bauplan-mcp-server/refs/heads/main/skills/new-pipeline/SKILL.md
curl -o .claude/skills/creating-bauplan-pipelines/examples.md https://raw.githubusercontent.com/BauplanLabs/bauplan-mcp-server/refs/heads/main/skills/new-pipeline/examples.md
curl -o .claude/skills/wap-ingestion/SKILL.md https://raw.githubusercontent.com/BauplanLabs/bauplan-mcp-server/refs/heads/main/skills/wap/SKILL.md
curl -o .claude/skills/explore-data/SKILL.md https://raw.githubusercontent.com/BauplanLabs/bauplan-mcp-server/refs/heads/main/skills/explore-data/SKILL.md

This script will download the following files from the bauplan-mcp-server repository and organize them in your repository using this structure below:

  1. CLAUDE.md Agent Playbook - Instructions for how AI agents should work with Bauplan.
  2. Bauplan CLI Reference - Complete Bauplan CLI command documentation.
  3. Skills - Specialized workflows for pipelines, ingestion, and exploration.

Folder structure

your-repository/
├── .claude/
│   ├── CLAUDE.md                                # Agent playbook
│   ├── bauplan-reference/
│   │   └── bauplan_cli.md                       # CLI documentation
│   └── skills/
│       ├── creating-bauplan-pipelines/
│       │   ├── SKILL.md                         # Pipeline creation skill
│       │   └── examples.md                      # (if available)
│       ├── wap-ingestion/
│       │   └── SKILL.md                         # WAP ingestion skill
│       └── explore-data/
│           └── SKILL.md                         # Data exploration skill
├── .gitignore
└── (your pipeline code and data projects go here)

Why this structure?

  • .claude/ directory is where Claude Code and similar agents look for project context
  • reference/ contains documentation the agent can consult
  • skills/ contains folders, each representing a specialized workflow
  • Each skill folder has a SKILL.md file with the skill definition and instructions

How Agent-Assisted Workflows Work​

Unlike traditional step-by-step instructions, agent-assisted workflows are conversational. You describe what you want to accomplish, and the AI agent chooses the right approach (e.g. Skills, MCP server or CLI commands) and writes and executes commands.

This tutorial is centered around Skills to make it easier to go through complex workflows, such as data exploration, data pipelines and data import.

TaskApproachSkill Used
Explore, discover an profile dataDirect CLI commandsexplore-data
Ingest data from object storage into the LakehouseCode generation, PySDKwap-ingestion
Build and run transformation pipelinesCode generation, Direct CLI,creating-bauplan-pipelines