The data team doesn't have a standard approach for AI-assisted development — this guide fills that gap. It's based on what's already been working for several teammates, so everyone has a solid starting point rather than figuring it out from scratch.
This guide covers setup for:
-**OpenCode** — a terminal-based AI coding agent
-**Snowflake/dbt MCP servers** (optional, but highly recommended)
A more comprehensive guide is available in the [internal handbook](https://internal.gitlab.com/handbook/ai-security-at-gitlab/guides/setup-guides/opencode-setup/). The steps below are a simplified, data-team-specific version.
### Step 1: Install OpenCode
```bash
curl -fsSL https://opencode.ai/install | bash
```
### Step 2: Verify the installation
Check that OpenCode is available in your PATH:
```bash
which opencode
```
If this returns a path (e.g., `/Users/yourusername/.opencode/bin/opencode`), you're good to proceed to Step 3.
**If `which opencode` returns nothing**, add OpenCode to your PATH by adding this line to your `~/.zshrc`:
```bash
export PATH=~/.opencode/bin:$PATH
```
Then reload your shell:
```bash
source ~/.zshrc
```
Now verify the installation:
```bash
opencode --version
```
You should see the installed version number.
### Step 3: Start OpenCode from the analytics repo
```bash
cd analytics/
opencode
```
### Step 4: Configure GitLab Duo as your AI provider
GitLab Duo uses OAuth — no token to create or manage.
1. Run `/connect` inside OpenCode and select **GitLab Duo**
2. OpenCode will open your browser to complete the OAuth flow
3. Sign in with your `@gitlab.com` account and authorise the app
4. You'll be redirected back to OpenCode automatically
### Step 5: Apply the Golden Config
Apply the config from the [OpenCode Golden Path](https://internal.gitlab.com/handbook/ai-security-at-gitlab/guides/golden-configs/opencode/#golden-path-config).
> **Note:** Use `~/.config/opencode/opencode.jsonc` rather than `opencode.json` — the `.jsonc` extension allows comments, which is useful for annotating your config.
### Step 6: Set `plan` as your default agent
Open `~/.config/opencode/config.json` and add `default_agent`:
```jsonc
{
"$schema":"https://opencode.ai/config.json",
...
"default_agent":"plan"
}
```
This keeps you in the safer, more deliberate mode by default — you switch to Build explicitly when you're ready to execute.
### Step 7: Review the Agent Usage Guide
Before you start using OpenCode, review the [Agent Usage Guide](agent-usage-guide.md) to understand:
- How agents and MCPs work
- Configuration best practices (global vs project-level)
### Snowflake MCP Server (Optional but Highly Recommended)
Connecting OpenCode to Snowflake MCP allows an LLM agent to query Snowflake directly during an OpenCode session.
To set up, run the [setup_snowflake_mcp.sh script](https://gitlab.com/gitlab-data/analytics/-/blob/master/admin/setup_snowflake_mcp.sh?ref_type=heads) with these commands:
Controls which Snowflake tool groups are enabled and which SQL statement types are permitted. The defaults enable object inspection and query execution while disabling destructive operations (`Drop`, `Delete`).
The only other prerequisite is having the dbt virtualenv set up — if you've already run `make run-dbt` for normal dbt development, you're good to go.
---
## MacWhisper for Voice Prompting (Optional)
Typing out detailed prompts is slow. [MacWhisper](https://goodsnooze.gumroad.com/l/macwhisper) is a macOS voice-to-text app that makes it much faster to describe context and work through problems out loud — particularly for longer prompts where you'd otherwise spend more time typing than thinking.
It's noticeably more accurate than built-in macOS Dictation app, and unlike cloud-based transcription it runs entirely on-device, so nothing leaves your machine.
An AI model is a single call — you send a prompt, you get a response. An agent is that same model running in a loop: it receives your request, decides on an action (read a file, run a command, edit code), observes the result, and repeats until the task is done.
For a deeper dive, see Anthropic's [building effective agents](https://www.anthropic.com/research/building-effective-agents) writeup.
## How MCPs Work
MCP (Model Context Protocol) servers extend what an agent can do by connecting it to external tools and data sources — think Snowflake, GitLab, dbt, Slack. Each active MCP adds to the agent's context window, so only enable what you actually need for the task at hand.
## Configuration
OpenCode uses two config files that merge at runtime — a global config (`~/.opencode/config.json`) and a project-level config (`.opencode/config.json` at the repo root). Project settings override global ones when they collide.
Keep your global config minimal. The main thing worth putting there is MCPs you need in every session regardless of what you're working on. Everything else — especially repo-specific MCPs like `dbt-mcp` — belongs in the project config. For example, `dbt-mcp` lives only in the analytics repo config since it's only relevant there.
A good rule of thumb: if you'd want the MCP active even when you open OpenCode outside of any project, it goes global. Otherwise, keep it local.
## Best Practices for Prompting
Keep context lean. Start a new conversation any time you shift focus — a new feature, a different bug, an unrelated review. When in doubt, fresh window. In OpenCode, use the `/new` command to do that. This improves quality of responses as well as costs
If a skill exists for what you're doing, use it — skills give the agent domain-specific context it wouldn't otherwise have.
## When to Use Plan vs Build Mode
OpenCode has two primary modes:
-**Plan** — reviews your request and relevant code, then proposes a detailed approach *before* making any changes
-**Build** — executes changes directly
Always run Plan first for anything non-trivial. It's surprisingly good at catching design issues before you're already mid-implementation.
If you've set `plan` as your default agent (recommended in the [setup guide](agent-setup.md#step-6-set-plan-as-your-default-agent)), you'll be in Plan mode by default. Switch to Build mode explicitly when you're ready to execute.
## Available Skills and Agents
Skills encode reusable, team-specific knowledge — conventions, workflows, and best practices that would otherwise need to be re-explained every session. Rather than prompting from scratch, invoking a skill gives the agent the right context immediately.
For a list of available skills developed by the Data Team, see the [Available Skills](agentic-tool-development.md#available-skills) section in the Agentic Tool Development guide.
@@ -45,3 +45,12 @@ Once ready, changes follow the same merge request workflow as any other code cha
The `AGENTS.md` file at the repository root serves as the entry point for agentic context — it describes the directory structure and conventions so that any AI coding assistant working in the repository can orient itself immediately.
As the field of agentic AI evolves rapidly, the team's conventions, tooling choices, and agent designs will be continuously re-evaluated. Patterns that work well today may be superseded by new capabilities in GitLab Duo or updated standards from the broader ecosystem, and the team will adapt accordingly.
## Available Skills
The Data Team's skills are maintained directly in the repositories where they're used. Browse the skills directories to see what's available:
-**[Analytics repository skills](https://gitlab.com/gitlab-data/analytics/-/tree/master/agents/skills?ref_type=heads)** - Skills for dbt, Snowflake, and analytics workflows
-**[Extract repository skills](https://gitlab.com/gitlab-data/extract/-/tree/main/agents/skills?ref_type=heads)** - Skills for data extraction and pipeline work
As of writing, there still are NOT many skills available, but we will be adding more regularly.
@@ -52,7 +52,7 @@ If you're working in your domain and spot something that affects another domain,
We develop agentic tools and AI skills collaboratively, using our team's GitLab repository as the single source of truth for all code. The principle is simple: when someone on the team builds a useful prompt, skill, or agent workflow, it doesn't live on their laptop - it goes into the repo so everyone can use it, learn from it, and improve it.
We iterate on these skills together, and every addition or change to the repository requires a peer review before merging. This keeps quality high, spreads knowledge across the team, and ensures we're building shared capability rather than individual shortcuts. We follow the [Data Team standards for agentic tool development](/handbook/enterprise-data/platform/agentic-tool-development/) as our baseline, and extend them where our team's use cases require it.
We iterate on these skills together, and every addition or change to the repository requires a peer review before merging. This keeps quality high, spreads knowledge across the team, and ensures we're building shared capability rather than individual shortcuts. We follow the [Data Team standards for agentic tool development](../ai/agentic-tool-development.md) as our baseline, and extend them where our team's use cases require it.
