monte-carlo-validation-notebook – Data & Science skill for AI agents

> Tip: This skill works well with Sonnet. Run /model sonnet before invoking for faster generation.

Generate a SQL Notebook with validation queries for dbt changes.

Arguments: $ARGUMENTS

The import URL contains reversible notebook SQL and metadata. Review the destination and content before --open; no automatic browser import is performed. Require trusted base/head compiled relation metadata rather than treating the helper’s hardcoded PROD convention as authoritative.

Detailed Guide

Read [the detailed guide](references/detailed-guide.md) before executing this skill. It retains the complete procedure and reference material. Treat its safety, prerequisites, and validation requirements as mandatory. For focused work, load the relevant sections; for end-to-end work, read the guide completely.

When to Use

Use this skill when the user wants to validate dbt model or snapshot changes with Monte Carlo SQL Notebook queries, either from a GitHub PR or a local dbt repository.

Parse the arguments:

• Target (required): first argument — a GitHub PR URL or local dbt repo path
• MC Base URL (optional): --mc-base-url <URL> — defaults to https://getmontecarlo.com
• Models (optional): --models <model1,model2,...> — comma-separated list of model filenames (without .sql extension) to generate queries for. Only these models will be included. By default, all changed models are included up to a maximum of 10.

---

Setup

Prerequisites:

• gh (GitHub CLI) — required for PR mode. Must be authenticated (gh auth status).
• python3 — required for helper scripts.
• pyyaml — install with pip3 install pyyaml (or pip install pyyaml, uv pip install pyyaml, etc.)

Dialect gate: These templates require warehouse-specific review for identifiers, composite distinct, timestamps and intervals. LIMIT bounds returned rows, not scan cost. Use read-only credentials, timeouts and scan budgets; do not execute queries as part of notebook generation.

This skill includes two helper scripts in ${CLAUDE_PLUGIN_ROOT}/skills/monte-carlo-validation-notebook/scripts/:

• resolve_dbt_schema.py - Resolves dbt model output schemas from dbt_project.yml routing rules and model config overrides.
• generate_notebook_url.py - Encodes notebook YAML into a base64 import URL and opens it in the browser.

Mode Detection

Auto-detect mode from the target argument:

• If target looks like a URL (contains :// or github.com) -> PR mode
• If target is a path (., /path/to/repo, relative path) -> Local mode

---

Context

This command generates a SQL Notebook containing validation queries for dbt changes. The notebook can be opened in the MC Bridge SQL Notebook interface for interactive validation.

The output is an import URL that opens directly in the notebook interface:

<MC_BASE_URL>/notebooks/import#<base64-encoded-yaml>

Key Features:

• Database Parameters: Two text parameters (prod_db and dev_db) for selecting databases
• Schema Inference: Automatically infers schema per model from dbt_project.yml and model configs
• Single-table queries: Basic validation queries using {{prod_db}}.<SCHEMA>.<TABLE>
• Comparison queries: Before/after queries comparing {{prod_db}} vs {{dev_db}}
• Flexible usage: Users can set both parameters to the same database for single-database analysis

Notebook YAML Spec Reference

Key structure:

version: 1
metadata:
  id: string           # kebab-case + random suffix
  name: string         # display name
  created_at: string   # ISO 8601
  updated_at: string   # ISO 8601
default_context:       # optional database/schema context
  database: string
  schema: string
cells:
  - id: string
    type: sql | markdown | parameter
    content: string    # SQL, markdown, or parameter config (JSON)
    display_type: table | bar | timeseries

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.