Claude Cursor Skill

monte-carlo-prevent

Shift-left safety net for dbt/SQL model edits. Runs change impact assessment before edits, generates SQL validation queries after, and executes them via `/mc-validate run`. Delegates health and monitor creation to peer skills.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download monte-carlo-data-mc-agent-toolkit-skills_prevent-bcc7373.zip · 39 KB

Install

skills CLI npx skills add https://github.com/monte-carlo-data/mc-agent-toolkit/tree/main/skills/prevent
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install monte-carlo-data-mc-agent-toolkit@llmmart
Git git clone https://github.com/monte-carlo-data/mc-agent-toolkit.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole monte-carlo-data/mc-agent-toolkit collection as a plugin from our marketplace. Git is the plain clone.

README

Monte Carlo Prevent Skill

Bring Monte Carlo data observability into your editor — automatically, before you write a single line of code.

What this does

When you reference a dbt model or table, Monte Carlo context comes to you: table health, active alerts, lineage, and downstream blast radius. Your AI editor uses that context to shape the code it writes — not just surface it. If you try to rename a column with 500 downstream dependents, the editor recommends a safe transition strategy and explains why, citing the specific MC data it found. When you add new logic, it generates and deploys the right monitor for your logic — validation, metric, comparison, or custom SQL — before you merge. When you're done with a change, it generates targeted validation queries — tailored to the specific columns, filters, and business logic you modified — so you can verify the change behaved as intended before merging.

Editor & Stack Compatibility

The skill works with any AI editor that supports MCP and the Agent Skills format — including Claude Code, Cursor, and VS Code.

For data stacks, compatibility varies by how you work:

Stack Support Notes
dbt + any MC-supported warehouse ✅ Full Optimized and tested
SQL-first, no dbt 🟡 Partial Core workflows work via explicit prompting; auto-triggers on file open coming soon
Databricks notebooks 🟡 Partial Health check, impact assessment, and alert triage work; file-based triggers coming soon
SQLMesh 🟡 Partial Core workflows work; native SQLMesh project structure support coming soon
PySpark / non-SQL pipelines 🟠 Limited Manual prompting only; broader support on the roadmap

Coming shortly: Generic SQL file triggers, Databricks notebook support, and SQLMesh project structure support — so auto-activation works regardless of your transformation tool.

Core workflows — table health check, change impact assessment, alert triage, and monitor generation — work for any warehouse supported by Monte Carlo.

Prerequisites

  • Claude Code, Cursor, VS Code or any editors with MCP support
  • Monte Carlo account with Editor role or above
  • MC CLI installed for monitor deployment (pip install montecarlodata)

Setup

Via the mc-agent-toolkit plugin (recommended)

Install the plugin for your editor — it bundles the skill, hooks, MCP server, and permissions automatically. See the main README for editor-specific instructions.

Standalone

  1. Configure the Monte Carlo MCP server:

    claude mcp add --transport http monte-carlo-mcp https://mcp.getmontecarlo.com/mcp
    
  2. Install the skill:

    npx skills add monte-carlo-data/mc-agent-toolkit --skill prevent
    
  3. Authenticate: run /mcp in your editor, select monte-carlo-mcp, and complete the OAuth flow.

  4. Verify: ask your editor "Test my Monte Carlo connection" — it should call testConnection and confirm.

Legacy: header-based auth (for MCP clients without HTTP transport)

If your MCP client doesn't support HTTP transport, use .mcp.json.example with npx mcp-remote and header-based authentication. See the MCP server docs for details.

How to use it

Open your dbt project (or any data engineering codebase) in your editor. Describe the change you want to make — or reference a model file together with an edit (@models/orders.sql add a column). The skill activates automatically when you express change intent; no special commands needed.

End-to-end flow

flowchart TD
    A["Describe a<br/>change"] --> B["Fetch table<br/>context<br/>(silent)"]
    B --> C["Impact<br/>assessment"]
    C --> D{"Proceed?"}
    D -- yes --> E["Edit<br/>applied"]
    E --> P["Post-edit prompt:<br/>generate validation<br/>queries?<br/>add monitor?"]
    P -- yes --> H["Generate<br/>validation queries"]
    P -- yes --> G["Generate<br/>monitor"]
    H --> R{"Run<br/>queries?"}
    R -- yes --> S["Build &amp; run"]

Impact assessment — Before any SQL edit (including filter changes, bugfixes, reverts, and parameter tweaks), prevent surfaces the change's blast radius: downstream models, active alerts, column exposure in recent queries, and monitor coverage. You get a risk tier (High / Medium / Low) and a recommendation tied to your specific change. If the data suggests your approach is risky, Claude proposes a safer alternative.

Validation queries — When you're ready to test a change, say "generate validation queries", "validate this change", or run /mc-validate. Prevent generates 3–5 targeted SQL queries based on what you actually changed — null checks, before/after row counts, distribution checks — saved to validation/<table_name>_<timestamp>.sql with inline comments describing a passing result.

Monitor coverage — After you finish an edit, if the impact assessment found a coverage gap, prevent prompts you to add a monitor. On yes, it hands off to monte-carlo-monitoring-advisor to produce a validation, metric, comparison, or custom SQL monitor as code.

Validate in sandbox (/mc-validate run) — Two-phase workflow. Run /mc-validate first to generate the queries, then /mc-validate run to execute them:

  • Build — parses your profiles.yml, classifies the resolved database, and runs dbt build --select <model> into your dev database.
  • Execute — substitutes <YOUR_DEV_DATABASE> in the generated SQL with a user-confirmed value, runs each query through the Snowflake MCP, and reports findings.

⚠️ Heads up on prod vs. dev detection. The build phase classifies your resolved target as personal / dev / shared-dev / prod / unknown from your profiles.yml and any hard-coded {{ config(database=...) }}, and hard-stops if it lands on prod. This is a safety net, not a guarantee — naming conventions vary across orgs and the classifier can be wrong (especially on unknown). You are still responsible for confirming the target database before approving the build. Read the value the skill surfaces and don't approve if it doesn't match where you intend to write.

Invocation modes:

Command What it does
/mc-validate Default = generate. Runs query generation only.
/mc-validate generate Explicit generate. Same as above.
/mc-validate run Runs Build + Execute. Requires queries already generated.
/mc-validate run --skip-build Runs Execute only — assumes you built manually. Requires queries already generated.
/mc-validate run --dev-db <NAME> Same as run, bypasses the dev-database prompt in Execute.

/mc-validate run prerequisites

The run subcommand only works if all three of the following are in place — otherwise the flow will fail mid-build with a confusing error. Verify before invoking:

  • dbt installed and a dbt_project.yml discoverable from the changed model (the workflow walks up from the model file to find it).
  • profiles.yml present (typically in ~/.dbt/profiles.yml) with a working Snowflake target. The skill parses it to resolve your dev database.
  • Snowflake MCP server registered in the editor session — the skill detects this by looking for an mcp__snowflake__* tool. Without it, queries cannot execute and the substituted SQL is left on disk for you to run manually.

The run subcommand performs a connection pre-flight check before kicking off the build. If any prerequisite is missing, it aborts early and tells you what to fix — rather than failing after a partial build.

Deploying generated monitors

When Claude generates a monitor, it saves the YAML to monitors/<table>.yml. Deploy with:

montecarlo monitors apply --dry-run    # preview
montecarlo monitors apply --auto-yes   # apply

Your project needs a montecarlo.yml config in the working directory:

version: 1
namespace: <your-namespace>
default_resource: <your-warehouse-name>

Troubleshooting

See TROUBLESHOOTING.md for common setup and runtime issues.

Skill manifest

Monte Carlo Prevent Skill

This skill brings Monte Carlo's data observability context directly into your editor. When you're modifying a dbt model or SQL pipeline, use it to surface table health, lineage, active alerts, and to generate monitors-as-code without leaving Claude Code.

Monte Carlo tool routing (required): Always call Monte Carlo MCP tools through this plugin's bundled server, whose fully-qualified tool names are mcp__plugin_mc-agent-toolkit_monte-carlo-mcp__<tool> (e.g. mcp__plugin_mc-agent-toolkit_monte-carlo-mcp__get_alerts). Bare tool names used in this skill (get_alerts, search, get_table, …) refer to that bundled server. If the session also has a separately-configured monte-carlo-mcp server, do not route to it — it may point at a different endpoint or credentials.

Reference files live next to this skill file. Use the Read tool (not MCP resources) to access them:

  • Full workflow step-by-step instructions: references/workflows.md (relative to this file)
  • MCP parameter details: references/parameters.md (relative to this file)
  • Troubleshooting: references/TROUBLESHOOTING.md (relative to this file)

When to activate this skill

Prevent is the edit-lifecycle skill. Activate only when the user expresses intent to change a dbt model. Bare file mentions, table-name mentions in passing, or general health questions are not prevent's territory — those belong to monte-carlo-asset-health and will activate that skill on their own.

Do not wait to be asked. Run the appropriate workflow automatically whenever the user:

  • Describes a planned change to a model (new column, join update, filter change, refactor) → STOP — run Workflow 1 first if it has not run for this table this session, then Workflow 2, before writing any code
  • Adds a new column, metric, or output expression to an existing model → same rule: Workflow 1 first (if not yet run for this table), then Workflow 2; the post-edit hook will offer Workflow 5 (monitor generation) afterward
  • References a model file with an edit verb in the same prompt (e.g. @models/clients/client_hub.sql add an is_active column) → same rule: Workflow 1 first, then Workflow 2

Present the W2 impact assessment as context the engineer needs before proceeding — not as a response to a question.

Workflow 1 runs silently when chained to Workflow 2

When the user expresses change intent, Workflow 1 invokes monte-carlo-asset-health purely as a data-gathering step. Read asset-health's report from your context, but do not relay the full report to the engineer — the user-facing artifact is Workflow 2's impact assessment, which already cites the relevant alerts / lineage / monitors. Showing both creates duplicate reading.

Two exceptions where you must surface output from W1 to the engineer:

  1. Disambiguation prompt. If asset-health returns multiple matches and asks the engineer to pick one, surface that question — the user must choose.
  2. Stop-the-world signals. If the table is already on fire (active critical alerts firing, freshness severely stale), say so in one short line before W2.

If Workflow 1 already ran for this table earlier in the session, skip directly to Workflow 2 — re-running asset-health is redundant.

When NOT to activate this skill

Do not invoke Monte Carlo tools for:

  • Seed files (files in seeds/ directory)
  • Analysis files (files in analyses/ directory)
  • One-off or ad-hoc SQL scripts not part of a dbt project
  • Configuration files (dbt_project.yml, profiles.yml, packages.yml)
  • Test files unless the user is specifically asking about data quality

If uncertain whether a file is a dbt model, check for {{ ref() }} or {{ source() }} Jinja references — if absent, do not activate.

Macros and snapshots — gate edits, skip auto-context

Macro files (macros/) and snapshot files (snapshots/) are not models, so do not auto-fetch Monte Carlo context (Workflow 1) when they are opened. However, macros are inlined into every model that calls them at compile time — a one-line macro change can silently alter dozens of models. Snapshots control historical tracking and are similarly sensitive.

The pre-edit hook gates these files. If the hook fires for a macro or snapshot, identify which models are affected and run the change impact assessment (Workflow 2) for those models before proceeding with the edit.

Peer-skill redirects

These requests have their own skills — do not run prevent for them:

  • "How is table X doing?" / "is X healthy?" / "check status of X" → monte-carlo-asset-health
  • "Create a monitor for X" / "what should I monitor?" / "set up freshness on X" (without an active edit context) → monte-carlo-monitoring-advisor

Prevent invokes asset-health and monitoring-advisor itself when its workflows need them (W1, W5); it does not duplicate their entry points.


REQUIRED: Change impact assessment before any SQL edit

Before editing or writing any SQL for a dbt model or pipeline, you MUST run Workflow 2.

This applies whenever the user expresses intent to modify a model — including phrases like:

  • "I want to add a column…"
  • "Let me add / I'm adding…"
  • "I'd like to change / update / rename…"
  • "Can you add / modify / refactor…"
  • "Let's add…" / "Add a <column> column"
  • Any other description of a planned schema or logic change
  • "Exclude / filter out / remove [records/customers/rows]…"
  • "Adjust / increase / decrease [threshold/parameter/value]…"
  • "Fix / bugfix / patch [issue/bug]…"
  • "Revert / restore / undo [change/previous behavior]…"
  • "Disable / enable [feature/logic/flag]…"
  • "Clean up / remove [references/columns/code]…"
  • "Implement [backend/feature] for…"
  • "Create [models/dbt models] for…" (when modifying existing referenced tables)
  • "Increase / decrease / change [max_tokens/threshold/date constant/numeric parameter]…"
  • Any change to a hardcoded value, constant, or configuration parameter within SQL
  • "Drop / remove / delete [column/field/table]"
  • "Rename [column/field] to [new name]"
  • "Add [column]" (short imperative form, e.g. "add a created_at column")
  • Any single-verb imperative command targeting a column, table, or model (e.g. "drop X", "rename Y", "add Z", "remove W")

Parameter changes (threshold values, date constants, numeric limits) appear safe but silently change model output. Treat them the same as logic changes for impact assessment purposes.

Do not write or edit any SQL until the change impact assessment (Workflow 2) has been presented to the user. The assessment must come first — not after the edit, not in parallel.


Pre-edit gate — check before modifying any file

Before calling Edit, Write, or MultiEdit on any .sql or dbt model file, you MUST check:

  1. Has the synthesis step been run for THIS SPECIFIC CHANGE in the current prompt?
  2. If YES → proceed with the edit
  3. If NO → stop immediately, run Workflow 2, present the full report with synthesis connected to this specific change. If risk is High or Medium: ask "Do you want me to proceed with the edit?" and wait for explicit confirmation. If risk is Low: use judgment — proceed if straightforward and no concerns found, otherwise ask before editing.

Important: "Workflow 2 already ran this session" is NOT sufficient to proceed. Each distinct change prompt requires its own synthesis step connecting the MC findings to that specific change.

The synthesis must reference the specific columns, filters, or logic being changed in the current prompt — not just general table health.

Example:

  • ✅ "Given 34 downstream models depend on is_paying_workspace, adding 'MC Internal' to the exclusion list will exclude these workspaces from all downstream health scores and exports. Confirm?"
  • ❌ "Workflow 2 already ran. Making the edit now."

The only exception: if the user explicitly acknowledges the risk and confirms they want to skip (e.g. "I know the risks, just make the change") — proceed but note the skipped assessment.

Available MCP tools

All tools are available via the monte-carlo-mcp MCP server.

Tool Purpose
testConnection Verify auth and connectivity
search Find tables/assets by name
getTable Schema, stats, metadata for a table
getAssetLineage Upstream/downstream dependencies (call with mcons array + direction)
getAlerts Active incidents and alerts
getMonitors Monitor configs — filter by table using mcons array
getQueriesForTable Recent query history
getQueryData Full SQL for a specific query
createValidationMonitorMac Generate validation monitors-as-code YAML
createMetricMonitorMac Generate metric monitors-as-code YAML
createComparisonMonitorMac Generate comparison monitors-as-code YAML
createCustomSqlMonitorMac Generate custom SQL monitors-as-code YAML
getValidationPredicates List available validation rule types
getAudiences List notification audiences
getDomains List MC domains
getUser Current user info

Core workflows

Each workflow has detailed step-by-step instructions in references/workflows.md (Read tool).

1. Asset health pre-fetch (silent delegation to asset-health)

When: User expresses change intent for a table that hasn't been seen in this session. What: Invokes monte-carlo-asset-health via the Skill tool to gather table state (health, upstream lineage, alerts, monitors). Then makes one direct get_asset_lineage(direction="DOWNSTREAM") call to complete the picture (asset-health only fetches upstream). The combined data is used as input to Workflow 2, not shown to the engineer. Two exceptions surface to the user: any disambiguation prompt, and stop-the-world signals (active critical alerts, severe staleness).

2. Change impact assessment — REQUIRED before modifying a model

When: Any intent to modify a dbt model's logic, columns, joins, or filters. What: Surfaces blast radius, downstream dependencies, active incidents, monitor coverage, and query exposure. Reuses asset-health's data when Workflow 1 ran earlier this session; otherwise calls get_table / get_alerts / get_asset_lineage / get_monitors directly. Produces a risk-tiered report with synthesis connecting findings to specific code recommendations.

3. Change validation queries

When: Explicit engineer request only (e.g. "validate this change", "ready to commit"), or via /mc-validate run. What: Generates 3–5 targeted SQL queries to verify the change behaved as intended. Uses Workflow 2 context — requires both impact assessment and file edit in session.

4. Validate change in sandbox — invoked by /mc-validate run

When: Only when the engineer invokes /mc-validate run (in any of its forms).

Pre-flight: run does not auto-generate. If no validation/<table>_<ts>.sql exists for the changed model(s), abort and tell the engineer to run /mc-validate (or /mc-validate generate) first.

What: Two-phase workflow.

  • W4.1 — Build. Parses profiles.yml, classifies the active database, detects hard-coded database: in the model's {{ config() }}, then runs dbt build --select <model> into the engineer's dev database. Refuses to build against shared prod. Skipped automatically for YAML/docs-only diffs and for /mc-validate run --skip-build.
  • W4.2 — Execute validation queries. Substitutes <YOUR_DEV_DATABASE> in Workflow-3 output with a user-confirmed value (or --dev-db <NAME> if supplied), runs a read-only pre-check on every query, executes via the Snowflake MCP, and reports per-query verdicts plus a consolidated summary.

Invocation matrix:

Invocation W3 (generate) W4.1 (Build) W4.2 (Execute)
/mc-validate yes — —
/mc-validate generate yes — —
/mc-validate run no — must already exist yes yes
/mc-validate run --skip-build no — must already exist no yes

run accepts both flags together: /mc-validate run --skip-build --dev-db <NAME>.

5. Add monitor (delegated to monitoring-advisor, post-edit)

When: Post-edit hook injects the coverage prompt (driven by MC_MONITOR_GAP from Workflow 2), or the engineer explicitly asks to add a monitor. What: Asks "Generate monitor definitions? (yes/no)". On yes, invokes monte-carlo-monitoring-advisor via the Skill tool with the model name and changed columns/logic. Prevent's responsibility ends at delegation — it does not wait for monitoring-advisor or emit a completion marker.

Workflow numbering note: numbers are assigned by execution order (W1 → W2 → optional W3 → optional W4 [W4.1 + W4.2] → optional W5), not by insertion order in this file. references/workflows.md is the source of truth.


Post-synthesis confirmation rules

Always end the synthesis with one clear, specific recommendation in plain English: "Given the above, I recommend: [specific action]"

If the risk is High or Medium: STOP and wait for confirmation before editing any file. You must ask the engineer and receive an explicit "yes", "go ahead", "proceed", or similar confirmation before making code changes. Say: "Do you want me to proceed with the edit?" Do NOT say: "Proceeding with the edit." — that skips the engineer's decision.

If the risk is Low: Use your judgment based on the synthesis findings. If the change is straightforward and the synthesis found no concerns, you may proceed. If anything is surprising or worth flagging, ask before editing.


Session markers

These markers coordinate between the skill and the plugin's hooks. Output each on its own line when the condition is met.

Impact check complete

After the engineer confirms (High/Medium) or after presenting the synthesis (Low), output one marker per assessed table. IMPORTANT: use only the table/model name, not the full MCON:

(Use the model filename without .sql extension — NOT "acme.analytics.orders" or "prod.public.client_hub")

How many markers to emit depends on how the assessment was triggered:

Hook-triggered (the pre-edit hook blocked an edit and instructed you to run the assessment): Be strict — only emit markers for tables whose lineage and monitor coverage were fetched directly via Monte Carlo tools in this session. If the engineer describes changes to multiple tables but only one was formally assessed, emit only one marker. The pre-edit hook will gate the other tables and prompt for their own Workflow 2 runs.

Voluntarily invoked (the engineer proactively asked for an impact assessment): Be looser — emit markers for all tables the assessment meaningfully covered, even if some were assessed via lineage context rather than direct MC tool calls. The engineer is already safety-conscious; don't force redundant assessments for tables they clearly considered.

Monitor coverage gap

When Workflow 2 finds zero custom monitors on a table's affected columns, output:

Use only the table/model name (NOT the full MCON). This allows the plugin's hooks to remind the engineer about monitor coverage at commit time. Only output this marker when the gap is specifically about the columns or logic being changed — not for general table-level monitor absence.

After the prompt is delivered, the post-edit / pre-commit hook clears the gap state internally so it won't re-prompt for the same gap; if the engineer edits the model again, Workflow 2 will re-evaluate from scratch and re-emit the marker only if a gap still exists.

Sandbox build ran (W4.1)

Emit after a successful dbt build in Workflow 4.1 (or after a deliberate skip — e.g. YAML-only diff or --skip-build — including the skip reason). One marker per model.

Validation executed (W4.2)

Emit after Workflow 4.2 finishes executing validation queries for a model, regardless of individual per-query verdicts. One marker per model.

Files (mc-agent-toolkit)
  • references
    • parameters.md 1 KB
      Loading…
    • TROUBLESHOOTING.md 1.5 KB
      Loading…
    • workflows.md 36 KB
      Loading…
  • scripts
    • sandbox
      • tests
        • conftest.py 256 B
          Loading…
        • test_classify_sandbox.py 1.1 KB
          Loading…
        • test_detect_hardcoded_db.py 1.6 KB
          Loading…
        • test_integration_smoke.py 2.8 KB
          Loading…
        • test_parse_profiles.py 3.1 KB
          Loading…
        • test_readonly_check.py 3.9 KB
          Loading…
        • test_substitute_placeholders.py 3.7 KB
          Loading…
      • classify_sandbox.py 1.5 KB
        Loading…
      • detect_hardcoded_db.py 1.2 KB
        Loading…
      • parse_profiles.py 3.3 KB
        Loading…
      • readonly_check.py 2.3 KB
        Loading…
      • substitute_placeholders.py 3.7 KB
        Loading…
  • README.md 8.1 KB
    # Monte Carlo Prevent Skill
    
    Bring Monte Carlo data observability into your editor — automatically, before you write a single line of code.
    
    ## What this does
    
    When you reference a dbt model or table, Monte Carlo context comes to you: table health, active alerts, lineage, and downstream blast radius. Your AI editor uses that context to shape the code it writes — not just surface it. If you try to rename a column with 500 downstream dependents, the editor recommends a safe transition strategy and explains why, citing the specific MC data it found. When you add new logic, it generates and deploys the right monitor for your logic — validation, metric, comparison, or custom SQL — before you merge. When you're done with a change, it generates targeted validation queries — tailored to the specific columns, filters, and business logic you modified — so you can verify the change behaved as intended before merging.
    
    ## Editor & Stack Compatibility
    
    The skill works with any AI editor that supports MCP and the Agent Skills format — including Claude Code, Cursor, and VS Code.
    
    For data stacks, compatibility varies by how you work:
    
    | Stack | Support | Notes |
    |---|---|---|
    | dbt + any MC-supported warehouse | ✅ Full | Optimized and tested |
    | SQL-first, no dbt | 🟡 Partial | Core workflows work via explicit prompting; auto-triggers on file open coming soon |
    | Databricks notebooks | 🟡 Partial | Health check, impact assessment, and alert triage work; file-based triggers coming soon |
    | SQLMesh | 🟡 Partial | Core workflows work; native SQLMesh project structure support coming soon |
    | PySpark / non-SQL pipelines | 🟠 Limited | Manual prompting only; broader support on the roadmap |
    
    **Coming shortly:** Generic SQL file triggers, Databricks notebook support, and SQLMesh project structure support — so auto-activation works regardless of your transformation tool.
    
    Core workflows — table health check, change impact assessment, alert triage, and monitor generation — work for any warehouse supported by Monte Carlo.
    
    
    ## Prerequisites
    
    - Claude Code, Cursor, VS Code or any editors with MCP support
    - Monte Carlo account with Editor role or above
    - [MC CLI](https://docs.getmontecarlo.com/docs/using-the-cli) installed for monitor deployment (`pip install montecarlodata`)
    
    ## Setup
    
    ### Via the mc-agent-toolkit plugin (recommended)
    
    Install the plugin for your editor — it bundles the skill, hooks, MCP server, and permissions automatically. See the [main README](../../README.md#installing-the-plugin-recommended) for editor-specific instructions.
    
    ### Standalone
    
    1. Configure the Monte Carlo MCP server:
       ```
       claude mcp add --transport http monte-carlo-mcp https://mcp.getmontecarlo.com/mcp
       ```
    
    2. Install the skill:
       ```bash
       npx skills add monte-carlo-data/mc-agent-toolkit --skill prevent
       ```
    
    3. Authenticate: run `/mcp` in your editor, select `monte-carlo-mcp`, and complete the OAuth flow.
    
    4. Verify: ask your editor "Test my Monte Carlo connection" — it should call `testConnection` and confirm.
    
    <details>
    <summary>Legacy: header-based auth (for MCP clients without HTTP transport)</summary>
    
    If your MCP client doesn't support HTTP transport, use `.mcp.json.example` with `npx mcp-remote` and header-based authentication. See the [MCP server docs](https://docs.getmontecarlo.com/docs/mcp-server) for details.
    
    </details>
    
    ## How to use it
    
    Open your dbt project (or any data engineering codebase) in your editor. Describe the change you want to make — or reference a model file together with an edit (`@models/orders.sql add a column`). The skill activates automatically when you express change intent; no special commands needed.
    
    ### End-to-end flow
    
    ```mermaid
    flowchart TD
        A["Describe a<br/>change"] --> B["Fetch table<br/>context<br/>(silent)"]
        B --> C["Impact<br/>assessment"]
        C --> D{"Proceed?"}
        D -- yes --> E["Edit<br/>applied"]
        E --> P["Post-edit prompt:<br/>generate validation<br/>queries?<br/>add monitor?"]
        P -- yes --> H["Generate<br/>validation queries"]
        P -- yes --> G["Generate<br/>monitor"]
        H --> R{"Run<br/>queries?"}
        R -- yes --> S["Build &amp; run"]
    ```
    
    **Impact assessment** — Before any SQL edit (including filter changes, bugfixes, reverts, and parameter tweaks), prevent surfaces the change's blast radius: downstream models, active alerts, column exposure in recent queries, and monitor coverage. You get a risk tier (High / Medium / Low) and a recommendation tied to your specific change. If the data suggests your approach is risky, Claude proposes a safer alternative.
    
    **Validation queries** — When you're ready to test a change, say "generate validation queries", "validate this change", or run `/mc-validate`. Prevent generates 3–5 targeted SQL queries based on what you actually changed — null checks, before/after row counts, distribution checks — saved to `validation/<table_name>_<timestamp>.sql` with inline comments describing a passing result.
    
    **Monitor coverage** — After you finish an edit, if the impact assessment found a coverage gap, prevent prompts you to add a monitor. On yes, it hands off to `monte-carlo-monitoring-advisor` to produce a validation, metric, comparison, or custom SQL monitor as code.
    
    **Validate in sandbox (`/mc-validate run`)** — Two-phase workflow. Run `/mc-validate` first to generate the queries, then `/mc-validate run` to execute them:
    
    - **Build** — parses your `profiles.yml`, classifies the resolved database, and runs `dbt build --select <model>` into your dev database.
    - **Execute** — substitutes `<YOUR_DEV_DATABASE>` in the generated SQL with a user-confirmed value, runs each query through the Snowflake MCP, and reports findings.
    
    > ⚠️ **Heads up on prod vs. dev detection.** The build phase classifies your
    > resolved target as `personal` / `dev` / `shared-dev` / `prod` / `unknown`
    > from your `profiles.yml` and any hard-coded `{{ config(database=...) }}`,
    > and hard-stops if it lands on `prod`. This is a safety net, not a
    > guarantee — naming conventions vary across orgs and the classifier can be
    > wrong (especially on `unknown`). **You are still responsible for confirming
    > the target database before approving the build.** Read the value the skill
    > surfaces and don't approve if it doesn't match where you intend to write.
    
    **Invocation modes:**
    
    | Command | What it does |
    |---|---|
    | `/mc-validate` | Default = generate. Runs query generation only. |
    | `/mc-validate generate` | Explicit generate. Same as above. |
    | `/mc-validate run` | Runs **Build + Execute**. Requires queries already generated. |
    | `/mc-validate run --skip-build` | Runs **Execute only** — assumes you built manually. Requires queries already generated. |
    | `/mc-validate run --dev-db <NAME>` | Same as `run`, bypasses the dev-database prompt in Execute. |
    
    #### `/mc-validate run` prerequisites
    
    The `run` subcommand only works if all three of the following are in place — otherwise the flow will fail mid-build with a confusing error. Verify before invoking:
    
    - **dbt installed** and a `dbt_project.yml` discoverable from the changed model (the workflow walks up from the model file to find it).
    - **`profiles.yml`** present (typically in `~/.dbt/profiles.yml`) with a working Snowflake target. The skill parses it to resolve your dev database.
    - **Snowflake MCP server** registered in the editor session — the skill detects this by looking for an `mcp__snowflake__*` tool. Without it, queries cannot execute and the substituted SQL is left on disk for you to run manually.
    
    The `run` subcommand performs a connection pre-flight check before kicking off the build. If any prerequisite is missing, it aborts early and tells you what to fix — rather than failing after a partial build.
    
    ### Deploying generated monitors
    
    When Claude generates a monitor, it saves the YAML to `monitors/<table>.yml`. Deploy with:
    
    ```bash
    montecarlo monitors apply --dry-run    # preview
    montecarlo monitors apply --auto-yes   # apply
    ```
    
    Your project needs a `montecarlo.yml` config in the working directory:
    
    ```yaml
    version: 1
    namespace: <your-namespace>
    default_resource: <your-warehouse-name>
    ```
    
    ## Troubleshooting
    
    See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common setup and runtime issues.
    
  • SKILL.md 18.6 KB
    ---
    name: monte-carlo-prevent
    description: Shift-left safety net for dbt/SQL model edits. Runs change impact assessment before edits, generates SQL validation queries after, and executes them via `/mc-validate run`. Delegates health and monitor creation to peer skills.
    when_to_use: |
      Invoke when the user expresses intent to change a dbt or SQL model — adding, dropping, renaming, refactoring a column or filter, fixing a bug in model logic, tweaking a parameter, or referencing a model file paired with an edit verb. Also invoke when the user asks to "validate this change", "verify my edit", or runs `/mc-validate` / `/mc-validate run`.
      Example triggers: "add an is_active column to client_hub", "refactor the join logic in stg_payments", "drop the legacy_id column from dim_users", "@models/orders.sql add a filter", "/mc-validate run".
    
      Do NOT invoke for:
      - Plain health questions about a table ("how is X doing?", "is X healthy?") — those go to monte-carlo-asset-health.
      - Alert investigation or incident triage ("freshness alert on X", "why did X fail?") — those go to automated-triage or monte-carlo-incident-response.
      - Standalone monitor creation requests without an edit context ("create a monitor for X", "what should I monitor?", "show coverage gaps") — those go to monte-carlo-monitoring-advisor.
      - Performance or pipeline diagnosis ("why is X slow?", "investigate the query plan") — those go to monte-carlo-performance-diagnosis.
      - Edits to non-model files: seed CSVs (seeds/), analysis files (analyses/), dbt config (dbt_project.yml, profiles.yml, packages.yml).
      - Bare file opens or reads without an edit verb ("open stg_orders.sql so I can see what it does") — that's navigation, not change intent.
    bucket: Prevent
    version: 1.0.0
    ---
    
    # Monte Carlo Prevent Skill
    
    This skill brings Monte Carlo's data observability context directly into your editor. When you're modifying a dbt model or SQL pipeline, use it to surface table health, lineage, active alerts, and to generate monitors-as-code without leaving Claude Code.
    
    > **Monte Carlo tool routing (required):** Always call Monte Carlo MCP tools through this plugin's
    > bundled server, whose fully-qualified tool names are
    > `mcp__plugin_mc-agent-toolkit_monte-carlo-mcp__<tool>` (e.g.
    > `mcp__plugin_mc-agent-toolkit_monte-carlo-mcp__get_alerts`). Bare tool names used in this skill
    > (`get_alerts`, `search`, `get_table`, …) refer to that bundled server. If the session also has a
    > separately-configured `monte-carlo-mcp` server, do **not** route to it — it may point at a
    > different endpoint or credentials.
    
    Reference files live next to this skill file. **Use the Read tool** (not MCP resources) to access them:
    
    - Full workflow step-by-step instructions: `references/workflows.md` (relative to this file)
    - MCP parameter details: `references/parameters.md` (relative to this file)
    - Troubleshooting: `references/TROUBLESHOOTING.md` (relative to this file)
    
    ## When to activate this skill
    
    **Prevent is the edit-lifecycle skill.** Activate only when the user expresses
    intent to change a dbt model. Bare file mentions, table-name mentions in
    passing, or general health questions are **not** prevent's territory — those
    belong to `monte-carlo-asset-health` and will activate that skill on their own.
    
    **Do not wait to be asked.** Run the appropriate workflow automatically whenever the user:
    
    - Describes a planned change to a model (new column, join update, filter change, refactor) → **STOP — run Workflow 1 first if it has not run for this table this session, then Workflow 2, before writing any code**
    - Adds a new column, metric, or output expression to an existing model → same rule: Workflow 1 first (if not yet run for this table), then Workflow 2; the post-edit hook will offer Workflow 5 (monitor generation) afterward
    - References a model file with an edit verb in the same prompt (e.g. `@models/clients/client_hub.sql add an is_active column`) → same rule: Workflow 1 first, then Workflow 2
    
    Present the W2 impact assessment as context the engineer needs before proceeding — not as a response to a question.
    
    ### Workflow 1 runs silently when chained to Workflow 2
    
    When the user expresses change intent, Workflow 1 invokes `monte-carlo-asset-health`
    purely as a data-gathering step. Read asset-health's report from your context, but
    **do not relay the full report to the engineer** — the user-facing artifact is
    Workflow 2's impact assessment, which already cites the relevant alerts / lineage /
    monitors. Showing both creates duplicate reading.
    
    Two exceptions where you **must** surface output from W1 to the engineer:
    
    1. **Disambiguation prompt.** If asset-health returns multiple matches and asks
       the engineer to pick one, surface that question — the user must choose.
    2. **Stop-the-world signals.** If the table is already on fire (active critical
       alerts firing, freshness severely stale), say so in one short line before W2.
    
    If Workflow 1 already ran for this table earlier in the session, skip directly
    to Workflow 2 — re-running asset-health is redundant.
    
    ## When NOT to activate this skill
    
    Do not invoke Monte Carlo tools for:
    
    - Seed files (files in seeds/ directory)
    - Analysis files (files in analyses/ directory)
    - One-off or ad-hoc SQL scripts not part of a dbt project
    - Configuration files (dbt_project.yml, profiles.yml, packages.yml)
    - Test files unless the user is specifically asking about data quality
    
    If uncertain whether a file is a dbt model, check for {{ ref() }} or {{ source() }}
    Jinja references — if absent, do not activate.
    
    ### Macros and snapshots — gate edits, skip auto-context
    
    Macro files (`macros/`) and snapshot files (`snapshots/`) are **not** models, so
    do not auto-fetch Monte Carlo context (Workflow 1) when they are opened. However,
    macros are inlined into every model that calls them at compile time — a one-line
    macro change can silently alter dozens of models. Snapshots control historical
    tracking and are similarly sensitive.
    
    **The pre-edit hook gates these files.** If the hook fires for a macro or snapshot,
    identify which models are affected and run the change impact assessment (Workflow 2)
    for those models before proceeding with the edit.
    
    ### Peer-skill redirects
    
    These requests have their own skills — do not run prevent for them:
    
    - "How is table X doing?" / "is X healthy?" / "check status of X" → `monte-carlo-asset-health`
    - "Create a monitor for X" / "what should I monitor?" / "set up freshness on X" (without an active edit context) → `monte-carlo-monitoring-advisor`
    
    Prevent invokes asset-health and monitoring-advisor itself when its workflows
    need them (W1, W5); it does not duplicate their entry points.
    
    ---
    
    ## REQUIRED: Change impact assessment before any SQL edit
    
    **Before editing or writing any SQL for a dbt model or pipeline, you MUST run Workflow 2.**
    
    This applies whenever the user expresses intent to modify a model — including phrases like:
    
    - "I want to add a column…"
    - "Let me add / I'm adding…"
    - "I'd like to change / update / rename…"
    - "Can you add / modify / refactor…"
    - "Let's add…" / "Add a `<column>` column"
    - Any other description of a planned schema or logic change
    - "Exclude / filter out / remove [records/customers/rows]…"
    - "Adjust / increase / decrease [threshold/parameter/value]…"
    - "Fix / bugfix / patch [issue/bug]…"
    - "Revert / restore / undo [change/previous behavior]…"
    - "Disable / enable [feature/logic/flag]…"
    - "Clean up / remove [references/columns/code]…"
    - "Implement [backend/feature] for…"
    - "Create [models/dbt models] for…" (when modifying existing referenced tables)
    - "Increase / decrease / change [max_tokens/threshold/date constant/numeric parameter]…"
    - Any change to a hardcoded value, constant, or configuration parameter within SQL
    - "Drop / remove / delete [column/field/table]"
    - "Rename [column/field] to [new name]"
    - "Add [column]" (short imperative form, e.g. "add a created_at column")
    - Any single-verb imperative command targeting a column, table, or model
      (e.g. "drop X", "rename Y", "add Z", "remove W")
    
    Parameter changes (threshold values, date constants, numeric limits) appear
    safe but silently change model output. Treat them the same as logic changes
    for impact assessment purposes.
    
    **Do not write or edit any SQL until the change impact assessment (Workflow 2) has been presented to the user.** The assessment must come first — not after the edit, not in parallel.
    
    ---
    
    ## Pre-edit gate — check before modifying any file
    
    **Before calling Edit, Write, or MultiEdit on any `.sql` or dbt model
    file, you MUST check:**
    
    1. Has the synthesis step been run for THIS SPECIFIC CHANGE in the
       current prompt?
    2. **If YES** → proceed with the edit
    3. **If NO** → stop immediately, run Workflow 2, present the full
       report with synthesis connected to this specific change.
       **If risk is High or Medium:** ask "Do you want me to proceed
       with the edit?" and wait for explicit confirmation.
       **If risk is Low:** use judgment — proceed if straightforward
       and no concerns found, otherwise ask before editing.
    
    **Important: "Workflow 2 already ran this session" is NOT sufficient
    to proceed.** Each distinct change prompt requires its own synthesis
    step connecting the MC findings to that specific change.
    
    The synthesis must reference the specific columns, filters, or logic
    being changed in the current prompt — not just general table health.
    
    Example:
    
    - ✅ "Given 34 downstream models depend on is_paying_workspace,
      adding 'MC Internal' to the exclusion list will exclude these
      workspaces from all downstream health scores and exports.
      Confirm?"
    - ❌ "Workflow 2 already ran. Making the edit now."
    
    The only exception: if the user explicitly acknowledges the risk
    and confirms they want to skip (e.g. "I know the risks, just make
    the change") — proceed but note the skipped assessment.
    
    ## Available MCP tools
    
    All tools are available via the `monte-carlo-mcp` MCP server.
    
    | Tool                         | Purpose                                                              |
    | ---------------------------- | -------------------------------------------------------------------- |
    | `testConnection`             | Verify auth and connectivity                                         |
    | `search`                     | Find tables/assets by name                                           |
    | `getTable`                   | Schema, stats, metadata for a table                                  |
    | `getAssetLineage`            | Upstream/downstream dependencies (call with mcons array + direction) |
    | `getAlerts`                  | Active incidents and alerts                                          |
    | `getMonitors`                | Monitor configs — filter by table using mcons array                  |
    | `getQueriesForTable`         | Recent query history                                                 |
    | `getQueryData`               | Full SQL for a specific query                                        |
    | `createValidationMonitorMac` | Generate validation monitors-as-code YAML                            |
    | `createMetricMonitorMac`     | Generate metric monitors-as-code YAML                                |
    | `createComparisonMonitorMac` | Generate comparison monitors-as-code YAML                            |
    | `createCustomSqlMonitorMac`  | Generate custom SQL monitors-as-code YAML                            |
    | `getValidationPredicates`    | List available validation rule types                                 |
    | `getAudiences`               | List notification audiences                                          |
    | `getDomains`                 | List MC domains                                                      |
    | `getUser`                    | Current user info                                                    |
    
    ## Core workflows
    
    Each workflow has detailed step-by-step instructions in `references/workflows.md` (Read tool).
    
    ### 1. Asset health pre-fetch (silent delegation to asset-health)
    
    **When:** User expresses change intent for a table that hasn't been seen in this session.
    **What:** Invokes `monte-carlo-asset-health` via the Skill tool to gather table state (health, upstream lineage, alerts, monitors). Then makes one direct `get_asset_lineage(direction="DOWNSTREAM")` call to complete the picture (asset-health only fetches upstream). The combined data is **used as input to Workflow 2**, not shown to the engineer. Two exceptions surface to the user: any disambiguation prompt, and stop-the-world signals (active critical alerts, severe staleness).
    
    ### 2. Change impact assessment — REQUIRED before modifying a model
    
    **When:** Any intent to modify a dbt model's logic, columns, joins, or filters.
    **What:** Surfaces blast radius, downstream dependencies, active incidents, monitor coverage, and query exposure. Reuses asset-health's data when Workflow 1 ran earlier this session; otherwise calls `get_table` / `get_alerts` / `get_asset_lineage` / `get_monitors` directly. Produces a risk-tiered report with synthesis connecting findings to specific code recommendations.
    
    ### 3. Change validation queries
    
    **When:** Explicit engineer request only (e.g. "validate this change", "ready to commit"), or via `/mc-validate run`.
    **What:** Generates 3–5 targeted SQL queries to verify the change behaved as intended. Uses Workflow 2 context — requires both impact assessment and file edit in session.
    
    ### 4. Validate change in sandbox — invoked by `/mc-validate run`
    
    **When:** Only when the engineer invokes `/mc-validate run` (in any of its forms).
    
    **Pre-flight:** `run` does **not** auto-generate. If no `validation/<table>_<ts>.sql` exists for the changed model(s), abort and tell the engineer to run `/mc-validate` (or `/mc-validate generate`) first.
    
    **What:** Two-phase workflow.
    - **W4.1 — Build.** Parses `profiles.yml`, classifies the active database, detects hard-coded `database:` in the model's `{{ config() }}`, then runs `dbt build --select <model>` into the engineer's dev database. Refuses to build against shared prod. Skipped automatically for YAML/docs-only diffs and for `/mc-validate run --skip-build`.
    - **W4.2 — Execute validation queries.** Substitutes `<YOUR_DEV_DATABASE>` in Workflow-3 output with a user-confirmed value (or `--dev-db <NAME>` if supplied), runs a read-only pre-check on every query, executes via the Snowflake MCP, and reports per-query verdicts plus a consolidated summary.
    
    **Invocation matrix:**
    
    | Invocation | W3 (generate) | W4.1 (Build) | W4.2 (Execute) |
    |---|---|---|---|
    | `/mc-validate` | yes | — | — |
    | `/mc-validate generate` | yes | — | — |
    | `/mc-validate run` | no — must already exist | yes | yes |
    | `/mc-validate run --skip-build` | no — must already exist | no | yes |
    
    `run` accepts both flags together: `/mc-validate run --skip-build --dev-db <NAME>`.
    
    ### 5. Add monitor (delegated to monitoring-advisor, post-edit)
    
    **When:** Post-edit hook injects the coverage prompt (driven by `MC_MONITOR_GAP` from Workflow 2), or the engineer explicitly asks to add a monitor.
    **What:** Asks "Generate monitor definitions? (yes/no)". On yes, invokes `monte-carlo-monitoring-advisor` via the Skill tool with the model name and changed columns/logic. Prevent's responsibility ends at delegation — it does not wait for monitoring-advisor or emit a completion marker.
    
    > **Workflow numbering note:** numbers are assigned by execution order (W1 → W2 → optional W3 → optional W4 [W4.1 + W4.2] → optional W5), not by insertion order in this file. `references/workflows.md` is the source of truth.
    
    ---
    
    ## Post-synthesis confirmation rules
    
    Always end the synthesis with one clear, specific recommendation in plain English:
    "Given the above, I recommend: [specific action]"
    
    **If the risk is High or Medium:** STOP and wait for confirmation before editing
    any file. You must ask the engineer and receive an explicit "yes", "go ahead",
    "proceed", or similar confirmation before making code changes.
    Say: "Do you want me to proceed with the edit?"
    Do NOT say: "Proceeding with the edit." — that skips the engineer's decision.
    
    **If the risk is Low:** Use your judgment based on the synthesis findings. If
    the change is straightforward and the synthesis found no concerns, you may
    proceed. If anything is surprising or worth flagging, ask before editing.
    
    ---
    
    ## Session markers
    
    These markers coordinate between the skill and the plugin's hooks. Output each
    on its own line when the condition is met.
    
    ### Impact check complete
    
    After the engineer confirms (High/Medium) or after presenting the synthesis (Low),
    output one marker per assessed table. **IMPORTANT: use only the table/model name, not the full MCON:**
    
    <!-- MC_IMPACT_CHECK_COMPLETE: <table_name> -->
    
    (Use the model filename without .sql extension — NOT "acme.analytics.orders" or "prod.public.client_hub")
    
    How many markers to emit depends on how the assessment was triggered:
    
    **Hook-triggered** (the pre-edit hook blocked an edit and instructed you to run
    the assessment): Be strict — only emit markers for tables whose lineage **and**
    monitor coverage were fetched directly via Monte Carlo tools in this session. If
    the engineer describes changes to multiple tables but only one was formally
    assessed, emit only one marker. The pre-edit hook will gate the other tables and
    prompt for their own Workflow 2 runs.
    
    **Voluntarily invoked** (the engineer proactively asked for an impact assessment):
    Be looser — emit markers for all tables the assessment meaningfully covered, even
    if some were assessed via lineage context rather than direct MC tool calls. The
    engineer is already safety-conscious; don't force redundant assessments for tables
    they clearly considered.
    
    ### Monitor coverage gap
    
    When Workflow 2 finds zero custom monitors on a table's affected columns, output:
    
    <!-- MC_MONITOR_GAP: <table_name> -->
    
    Use only the table/model name (NOT the full MCON). This allows the plugin's hooks
    to remind the engineer about monitor coverage at commit time. Only output this
    marker when the gap is specifically about the columns or logic being changed —
    not for general table-level monitor absence.
    
    After the prompt is delivered, the post-edit / pre-commit hook clears the gap
    state internally so it won't re-prompt for the same gap; if the engineer edits
    the model again, Workflow 2 will re-evaluate from scratch and re-emit the
    marker only if a gap still exists.
    
    ### Sandbox build ran (W4.1)
    
    Emit after a successful `dbt build` in Workflow 4.1 (or after a deliberate skip
    — e.g. YAML-only diff or `--skip-build` — including the skip reason). One marker
    per model.
    
    <!-- MC_BUILD_RAN: <table_name> -->
    
    ### Validation executed (W4.2)
    
    Emit after Workflow 4.2 finishes executing validation queries for a model,
    regardless of individual per-query verdicts. One marker per model.
    
    <!-- MC_VALIDATE_RAN: <table_name> -->
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.