opencode-skills-collection 3.1.12 → 3.1.13

package/bundled-skills/monte-carlo-performance-diagnosis/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: monte-carlo-performance-diagnosis
+description: "Diagnoses pipeline performance issues -- slow jobs, expensive queries, latency trends -- using Monte Carlo's cross-platform observability. Uses a tiered investigation approach: discover problems, bridge to affected tables, then drill into root causes. Activates when a user asks about..."
+risk: unknown
+source: https://github.com/monte-carlo-data/mc-agent-toolkit/tree/main/skills/performance-diagnosis
+source_repo: monte-carlo-data/mc-agent-toolkit
+source_type: community
+date_added: 2026-07-01
+license: Apache-2.0
+license_source: https://github.com/monte-carlo-data/mc-agent-toolkit/blob/main/LICENSE
+---
+
+# Monte Carlo Performance Diagnosis Skill
+
+This skill helps diagnose data pipeline performance issues using Monte Carlo's cross-platform observability data. It works across Airflow, dbt, Databricks, and warehouse query engines to find bottlenecks, detect regressions, and identify root causes.
+
+> **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:
+
+- Tiered investigation approach: `references/investigation-tiers.md` (relative to this file)
+- Query analysis patterns: `references/query-analysis.md` (relative to this file)
+
+## When to activate this skill
+
+Activate when the user:
+
+- Asks about slow pipelines, jobs, or queries
+- Wants to find expensive or costly queries
+- Mentions performance regressions or degradation
+- Asks "why is this pipeline slow?" or "what's using the most compute?"
+- Wants to compare performance over time or find bottleneck tasks
+- Asks about failed or futile query patterns
+
+## When NOT to activate this skill
+
+Do not activate when the user is:
+
+- Investigating data quality issues (use the prevent skill)
+- Looking at storage costs (use the storage-cost-analysis skill)
+- Creating monitors (use the monitoring-advisor skill)
+- Just querying data or exploring table contents
+
+## Prerequisites
+
+The following MCP tools must be available (connect to Monte Carlo's MCP server):
+
+**Discovery tools (Tier 1):**
+- `get_jobs_performance` -- find slow/failing jobs across Airflow, dbt, Databricks
+- `get_top_slow_queries` -- find slowest query groups by total runtime
+
+**Bridge tool:**
+- `get_tables_for_job` -- convert job MCONs to table MCONs
+
+**Diagnosis tools (Tier 2):**
+- `get_tasks_performance` -- drill into a job's individual tasks
+- `get_change_timeline` -- unified timeline of query changes, volume shifts, Airflow/dbt failures
+- `get_query_rca` -- root cause analysis for failed/futile queries
+- `get_query_latency_distribution` -- latency trend over time
+- `get_asset_lineage` -- trace upstream/downstream impact
+
+**Supporting tools:**
+- `get_warehouses` -- list available warehouses
+
+## Workflow
+
+### Step 1: Identify the scope
+
+Determine what the user wants to investigate:
+- **Specific job/pipeline**: User mentions a job name or pipeline
+- **Specific table**: User mentions a table that's slow to update
+- **General discovery**: User wants to find what's slow
+
+Call `get_warehouses` to list available warehouses. Match the user's context to a warehouse.
+
+### Step 2: Tier 1 -- Discovery
+
+If you don't have specific MCONs to investigate, start with discovery:
+
+1. **Find slow jobs**: Call `get_jobs_performance` with optional `integration_type` filter (AIRFLOW, DATABRICKS, DBT) if the user specifies a platform.
+   - Results include: job name, average duration, trend (7-day), run count, failure rate
+   - Look for: high `avgDuration`, negative `runDurationTrend7d`, high failure rates
+
+2. **Find expensive queries**: Call `get_top_slow_queries` with optional `warehouse_id` and `query_type` ("read" for SELECTs, "write" for INSERT/CREATE/MERGE).
+   - Results include: query hash, total runtime, average runtime, run count
+   - Look for: queries with high total runtime or high individual execution time
+
+Present the top findings to the user before drilling deeper. A typical investigation needs only 3-7 tool calls.
+
+**If both discovery tools return no results:** Tell the user no performance issues were found in the current time window. Suggest broadening the scope (different warehouse, longer time range, or a different platform filter).
+
+### Step 3: Bridge -- Job to Tables
+
+After Tier 1 identifies problematic jobs, convert to table MCONs:
+
+Call `get_tables_for_job(job_mcon=..., integration_type=...)` using the `integration_type` from the job performance results.
+
+This gives you the table MCONs needed for Tier 2 investigation.
+
+### Step 4: Tier 2 -- Diagnosis
+
+Now drill into root causes using the MCONs from discovery or the bridge:
+
+1. **Task bottleneck**: Call `get_tasks_performance` to find which specific task in a job is the bottleneck.
+
+2. **What changed?** Call `get_change_timeline` -- this is your most powerful tool. It returns a unified timeline of:
+   - Query text changes (schema modifications, new JOINs, filter changes)
+   - Volume shifts (row count spikes/drops)
+   - Airflow task failures
+   - dbt model failures
+   All in one call. Look for correlations: "query changed on day X, runtime doubled on day X+1."
+
+3. **Why are queries failing?** Call `get_query_rca` to get root cause analysis:
+   - **Failed** queries: errors, timeouts, permission issues
+   - **Futile** queries: queries that run but produce no useful output
+   - Patterns are pre-computed -- the tool groups failures by cause
+
+4. **Is latency degrading?** Call `get_query_latency_distribution` to see the trend:
+   - Compare p50 vs p95 -- if p95 >> p50 (>5x), the problem is outlier queries
+   - Look for step-changes in latency (sudden increase = regression)
+   - For step-change / regression-time-localization use cases, pass `bucket="1h"`. The default downsamples to daily on windows ≥ 3 days, which hides hour-level steps.
+
+5. **Trace impact**: Call `get_asset_lineage` with `direction="DOWNSTREAM"` to see what's affected by a slow table, or `direction="UPSTREAM"` to find what feeds it.
+
+### Step 5: Present findings
+
+Structure your response as:
+
+1. **Problem summary**: What's slow and by how much (with exact numbers from tools)
+2. **Root cause**: What changed or what's causing the issue
+3. **Impact**: What downstream systems are affected
+4. **Recommendations**: Specific actions to fix the issue
+
+### Important rules
+
+- **Quote tool numbers exactly.** If a tool returns "1282 runs, avg 22.5s", say exactly that. Never round, estimate, or fabricate numbers.
+- **Always compare to baselines.** Use 7-day trend data (`runDurationTrend7d`) to distinguish regressions from normal variance. Flag if trend data has less than 0.1 confidence.
+- **Stop when you have a root cause.** 3-7 tool calls is typical. More than 10 means you're over-investigating.
+- **Read vs write queries**: When the user asks about "reads" or "read queries", filter with `query_type="read"`. When they ask about "writes", use `query_type="write"`. Do NOT mix them.
+- **Never expose MCONs, UUIDs, or internal identifiers** to the user. Use human-readable names.
+- **Cross-platform**: This skill works across Airflow, dbt, and Databricks. Note which platform each finding comes from.
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/monte-carlo-remediation/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: monte-carlo-remediation
+description: Investigate and remediate data quality alerts using Monte Carlo MCP tools. Runs root cause analysis, assesses blast radius, discovers available tools (MCP/CLI/API), proposes and executes fixes, or escalates with full context when uncertain.
+risk: unknown
+source: https://github.com/monte-carlo-data/mc-agent-toolkit/tree/main/skills/remediation
+source_repo: monte-carlo-data/mc-agent-toolkit
+source_type: community
+date_added: 2026-07-01
+license: Apache-2.0
+license_source: https://github.com/monte-carlo-data/mc-agent-toolkit/blob/main/LICENSE
+---
+
+# Monte Carlo Remediation Skill
+
+This skill teaches you to investigate and remediate data quality issues detected by Monte Carlo. You use MC MCP tools to understand the alert context, run root cause analysis, assess blast radius, and then execute the appropriate remediation action using whatever external tools the user has connected.
+
+> **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:
+
+- Common remediation patterns and examples: `references/patterns.md` (relative to this file)
+- How to discover available tools at runtime: `references/tool-discovery.md` (relative to this file)
+- Safety rails and escalation criteria: `references/safety.md` (relative to this file)
+
+## When to activate this skill
+
+Activate when the user:
+
+- Asks to remediate, fix, or respond to a data quality alert or incident
+- Mentions a specific alert ID, incident, or data quality issue they want resolved
+- Says something like "fix the freshness issue on X", "remediate this alert", "handle this incident"
+- Asks to triage AND fix an alert (triage alone without remediation intent → use the prevent skill's Workflow 3 instead)
+- Wants to automate a response to a recurring data quality pattern
+- Asks "what should I do about this alert?" or "how do I fix this?"
+
+## When NOT to activate this skill
+
+Do not activate when the user is:
+
+- Just triaging or investigating an alert without remediation intent (use prevent skill's Workflow 3)
+- Creating or configuring monitors (use the monitoring-advisor skill)
+- Running a change impact assessment before code changes (use the prevent skill's Workflow 4)
+- Asking about general data quality best practices without a specific incident
+- Exploring table health or lineage without an active issue to fix
+
+---
+
+## Available tools
+
+### Monte Carlo MCP server (investigation + post-remediation)
+
+The Monte Carlo MCP server (`monte-carlo-mcp`) provides the investigation tools used in the workflows below. The workflows reference key tools by name (e.g., `get_alerts`, `run_troubleshooting_agent`, `get_asset_lineage`), but **use any Monte Carlo tool that helps** — the server has additional tools beyond what the workflows explicitly call out. Explore what's available.
+
+> **Note on tool call examples:** The code blocks below show key parameters to guide you. Always check the tool's own description for the complete parameter list and exact parameter names — they are authoritative.
+
+### External tools (remediation execution)
+
+Remediation actions are executed via whatever tools are available — MCP servers, CLI tools, or APIs. See Workflow 2 (Capability Discovery) and `references/tool-discovery.md` for how to detect and use them. Use whatever works; don't limit yourself to a prescribed list.
+
+---
+
+## Core workflow
+
+Follow these workflows in order. Each workflow builds on the context gathered by the previous one.
+
+### Workflow 1: Investigation
+
+**Goal:** Understand what happened, why it happened, and what's affected.
+
+Before proposing ANY remediation action, you MUST complete this investigation. Do not skip steps — incomplete context leads to wrong fixes.
+
+#### Step 1: Get alert context
+
+```
+get_alerts(
+  alert_ids=["<alert_id>"],
+)
+```
+
+If the user provided a table name instead of an alert ID:
+```
+search(query="<table_name>")
+→ extract MCON
+get_alerts(
+  table_mcons=["<mcon>"],
+  created_after="<7 days ago>",
+  created_before="<now>",
+  order_by="-createdTime",
+  statuses=["NOT_ACKNOWLEDGED", "WORK_IN_PROGRESS"]
+)
+```
+
+Extract from the alert: `alert_type` (Freshness, Volume, Schema Changes, etc.), `severity`, affected table MCONs, `created_time`.
+
+#### Step 2: Assess triage priority
+
+```
+alert_assessment(
+  incident_id="<alert_uuid>"
+)
+```
+
+This returns `incident_likelihood` (HIGH/MEDIUM/LOW), `alert_impact` (HIGH/MEDIUM/LOW), and a summary. Use this to decide urgency:
+
+- **HIGH impact + HIGH incident likelihood** → proceed immediately to Troubleshooting Agent (TSA) analysis
+- **LOW impact or LOW incident likelihood** → still run TSA, but note to the user that this may not warrant immediate remediation
+
+#### Step 3: Root cause analysis (TSA)
+
+**Always use async mode.** TSA analysis takes 4–8 minutes — sync mode will time out.
+
+```
+run_troubleshooting_agent(
+  incident_id="<alert_uuid>",
+  async_mode=true
+)
+```
+
+**While TSA runs, proceed with Steps 4–6 in parallel** — gather lineage, table context, and query data while waiting. Then poll for TSA results:
+
+```
+get_troubleshooting_agent_results(
+  incident_id="<alert_uuid>"
+)
+```
+
+Status values:
+- `not_found` → TSA hasn't been triggered yet
+- `running` → still analyzing (wait 30s initially, then 60s intervals)
+- `success` → results available
+- `failed` → check `full_response` for error; proceed with manual investigation
+
+**When TSA succeeds, read both the `tldr` and the verifications section.** The `tldr` summarizes the root cause — this is your primary input for choosing a remediation action. The `full_response` includes a "verifications to confirm the root cause" section with specific checks (queries to run, things to compare, upstream systems to inspect). These verifications are often actionable remediation steps themselves — use them to guide what to do next or present them to the user as concrete next steps.
+
+#### Step 4: Assess blast radius
+
+```
+get_asset_lineage(
+  mcons=["<affected_table_mcon>"],
+  direction="DOWNSTREAM"
+)
+```
+
+For BI report coverage:
+```
+get_downstream_bi_reports(
+  mcon="<affected_table_mcon>"
+)
+```
+
+Then for upstream investigation:
+```
+get_asset_lineage(
+  mcons=["<affected_table_mcon>"],
+  direction="UPSTREAM"
+)
+```
+
+Note: `has_relationships=false` means no dependencies tracked — do not assume missing relationships.
+
+#### Step 5: Gather table context
+
+```
+get_table(
+  mcon="<affected_table_mcon>",
+  include_fields=true,
+  include_table_capabilities=true
+)
+```
+
+Extract: last activity timestamps, row counts, schema, monitoring status, importance score.
+
+For key downstream tables identified in Step 4, also fetch their details:
+```
+get_table(mcon="<downstream_mcon>")
+```
+
+#### Step 6: Check alert context, monitoring, and recent queries
+
+```
+get_monitors(mcons=["<affected_table_mcon>"])
+```
+
+For **Custom SQL** or **Validation** alerts, also fetch the monitor configuration to understand the exact rule that breached:
+```
+get_monitors(
+  monitor_ids=["<monitor_id_from_alert>"],
+  include_fields=["config"]
+)
+```
+The config contains the SQL query or validation conditions — this tells you exactly what the monitor checks, which is essential for understanding what went wrong and what the fix should be.
+
+```
+get_queries_for_table(
+  mcon="<affected_table_mcon>",
+  query_type="destination",
+  limit=10
+)
+```
+
+Use `query_type="destination"` to find queries that write to this table (pipeline queries). This helps identify which pipeline or job is responsible for the data.
+
+#### Investigation summary
+
+**Wait for TSA to complete before presenting findings.** Do not present partial results — the TSA root cause analysis and its verifications section are critical for choosing the right remediation action. If TSA is still running, keep polling; gather Steps 4–6 in the meantime.
+
+After all steps are complete, synthesize your findings into a clear summary:
+
+1. **What happened:** alert type, when it fired, severity
+2. **Root cause:** TSA findings (or your best assessment if TSA failed)
+3. **TSA verifications:** specific checks from the TSA `full_response` that can confirm the root cause or serve as remediation steps
+4. **Blast radius:** N downstream consumers, any key assets affected
+5. **Pipeline context:** which queries/jobs write to this table, when they last ran
+6. **Monitoring:** what monitors exist, any gaps. Note recurring patterns (e.g., "16 incidents in 30 days" signals a chronic issue, not a one-off)
+
+Present this summary to the user before proceeding to remediation.
+
+---
+
+### Workflow 2: Capability discovery
+
+**Goal:** Determine what remediation actions are possible given the tools you have available.
+
+Before attempting any remediation action, you must know what tools you can use. You have three categories to check:
+
+1. **MCP servers** — scan your tool list for `mcp__*__*` patterns (e.g., `mcp__airflow__trigger_dag_run`)
+2. **CLI tools** — you have shell access; check for tools like `gh`, `dbt`, `airflow`, `curl` via `which <tool>`
+3. **APIs** — any service with a REST API is reachable via `curl` if you have the right credentials
+
+Don't assume any particular tool is available. But also don't assume MCP is the only option — a `gh pr create` via the CLI works just as well as a GitHub MCP tool.
+
+For detailed guidance on discovery across all three categories, read `references/tool-discovery.md`.
+
+#### Capability assessment
+
+After checking, summarize what's available:
+
+**Example:**
+> "For this remediation, I can:
+> - ✅ Investigate via Monte Carlo (MCP connected)
+> - ✅ Restart the Airflow DAG (Airflow MCP connected)
+> - ✅ Create a code fix (`gh` CLI available)
+> - ❌ Rerun the dbt job (no dbt Cloud MCP or `dbt` CLI found)"
+
+#### Graceful degradation
+
+When no tool (MCP, CLI, or API) is available for a needed action:
+
+1. **Always produce the remediation plan** — describe exactly what needs to happen, step by step
+2. **Provide runnable commands** — give the user the exact commands they can run manually (e.g., `airflow dags trigger <dag_id>`, `dbt run --select <model>`)
+3. **Present findings and ask for next steps** — tell the user what you found, what you recommend, and ask how they'd like to proceed
+4. **Document on the alert** — use `create_or_update_alert_comment` to record the diagnosis and recommended fix
+
+---
+
+### Workflow 3: Remediation execution
+
+**Goal:** Take the appropriate action to fix the root cause, with safety rails.
+
+Read `references/patterns.md` for detailed examples of common remediation patterns.
+
+#### Step 1: Select remediation action
+
+Based on the TSA root cause and available tools, determine the action:
+
+| Root Cause Signal (from TSA) | Typical Remediation | Required Capability |
+| ---------------------------- | ------------------- | ------------------- |
+| Pipeline/DAG failure or delay | Restart the failed pipeline or task | Pipeline orchestration |
+| dbt model failure | Rerun the failed dbt job | dbt operations |
+| Schema change (upstream) | Assess impact, update downstream models or revert | Code changes |
+| Volume anomaly (missing data) | Check upstream pipeline, trigger backfill | Pipeline orchestration + warehouse |
+| Volume anomaly (duplicate data) | Identify and remove duplicates, fix pipeline | Warehouse + code changes |
+| Permission/access error | Present findings, recommend user escalates to data platform team | None (user decides) |
+| Infrastructure issue | Present findings, recommend user escalates to platform/ops team | None (user decides) |
+| Unknown or complex root cause | Present full context and ask user for next steps | None (user decides) |
+
+**If the root cause maps to multiple possible actions**, present the options to the user with tradeoffs and let them choose.
+
+**If the root cause doesn't clearly map to any pattern**, read `references/patterns.md` for the "Unknown / complex" pattern, which focuses on presenting full context to the user and asking for direction.
+
+#### Step 2: Present the remediation plan
+
+**BEFORE executing anything**, present the plan to the user:
+
+> "Based on the investigation:
+>
+> **Root cause:** [TSA summary]
+> **Proposed action:** [what you want to do]
+> **Reasoning:** [why this action addresses the root cause]
+> **Risk:** [what could go wrong, blast radius]
+> **Rollback:** [how to undo if the fix causes new problems]"
+
+#### Step 3: Execute (with safety rails)
+
+Before executing, read `references/safety.md` for the full safety protocol. The essentials:
+
+- **Explain before executing** — never take action without telling the user what and why
+- **Confirm destructive operations** — wait for explicit user approval
+- **Ask the user when uncertain** — don't guess at a fix
+- **One action at a time** — execute one action, then decide next step
+- **Log everything** — document each action on the alert via `create_or_update_alert_comment`
+
+---
+
+### Workflow 4: Post-remediation
+
+**Goal:** Close out the incident properly — update status, document, and prevent recurrence.
+
+#### Step 1: Update the alert
+
+Ask the user what status to set:
+
+- `FIXED` — the root cause was identified and remediated
+- `EXPECTED` — the alert fired on expected behavior (e.g., planned maintenance)
+- `NO_ACTION_NEEDED` — the issue resolved itself or is not actionable
+
+Then call `update_alert(alert_id="<alert_uuid>", status="<chosen_status>")`.
+
+#### Step 2: Document the remediation
+
+```
+create_or_update_alert_comment(
+  alert_id="<alert_uuid>",
+  comment="## Remediation Summary\n\n**Root cause:** [TSA findings]\n**Action taken:** [what was done]\n**Result:** [outcome]\n**Remediated by:** AI agent via remediation skill\n**Timestamp:** [ISO timestamp]"
+)
+```
+
+#### Step 3: Consider prevention
+
+After remediating, briefly assess whether this issue is likely to recur:
+
+- **If the root cause is systemic** (e.g., a flaky pipeline, a missing monitor): suggest adding a monitor or creating a ticket to address the underlying issue
+- **If it was a one-off** (e.g., infrastructure blip, manual error): document and move on
+
+Do not automatically create monitors or tickets — suggest them and let the user decide.
+
+---
+
+## Common mistakes to avoid
+
+- **NEVER execute a remediation action without presenting the plan first.** The user must understand what you're about to do.
+- **NEVER skip the investigation phase.** A wrong diagnosis leads to a wrong fix — or worse, a fix that causes new problems.
+- **NEVER assume external MCP tools are available.** Always check first. A missing tool is not an error — present findings to the user and ask for next steps.
+- **NEVER chain multiple remediation actions without verifying each one.** One action at a time.
+- **NEVER modify data directly** (DELETE, UPDATE, DROP) without explicit user confirmation AND a clearly stated rollback plan.
+- **NEVER mark an alert as FIXED before verifying the fix.** Check that the underlying condition has actually improved.
+- **NEVER remediate silently.** Always document what was done via `create_or_update_alert_comment`.
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/monte-carlo-storage-cost-analysis/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: monte-carlo-storage-cost-analysis
+description: Analyze a warehouse for stale, unused, or redundant tables via the analyze_storage_costs MCP tool. Classifies waste patterns and table categories, computes safety tiers, and handles category drill-downs and lineage follow-ups.
+risk: unknown
+source: https://github.com/monte-carlo-data/mc-agent-toolkit/tree/main/skills/storage-cost-analysis
+source_repo: monte-carlo-data/mc-agent-toolkit
+source_type: community
+date_added: 2026-07-01
+license: Apache-2.0
+license_source: https://github.com/monte-carlo-data/mc-agent-toolkit/blob/main/LICENSE
+---
+
+# Monte Carlo Storage Cost Analysis Skill
+
+This skill analyzes a data warehouse for stale tables that can be removed to reduce storage costs. It delegates classification, safety scoring, and formatting to the `analyze_storage_costs` MCP tool, then presents the pre-formatted result verbatim and handles follow-up questions (category drill-downs, lineage checks).
+
+> **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 file (use the Read tool to access it):
+
+- Output contract and category keywords: `references/output-structure.md`
+
+## When to activate this skill
+
+Activate when the user:
+
+- Asks about storage costs, waste, or cleanup opportunities
+- Wants to find unused, unread, or stale tables
+- Asks "which tables can I drop?" or "what's costing us money?"
+- Mentions storage optimization, cost reduction, or warehouse cleanup
+- Wants to identify zombie tables, dead-end pipelines, or temporary/archive tables
+
+## When NOT to activate this skill
+
+Do not activate when the user is:
+
+- Just querying data or exploring table contents
+- Creating or modifying monitors (use the monitoring-advisor skill)
+- Investigating data quality incidents (use the prevent skill)
+- Looking at pipeline performance or query cost (use the performance-diagnosis skill)
+
+## Prerequisites
+
+The following MCP tools must be available (connect to Monte Carlo's MCP server):
+
+- `analyze_storage_costs` -- runs the full analysis pipeline and returns pre-formatted output
+- `get_asset_lineage` -- used only for follow-up lineage checks
+
+The `analyze_storage_costs` tool supports **Snowflake, BigQuery, Redshift, and Databricks** warehouses only. Other warehouse types are out of scope.
+
+## Workflow
+
+**Important:** These steps are internal instructions for you. Do NOT expose step numbers, step names, or the procedural structure to the user. Just act naturally.
+
+### Step 1: Identify the warehouse
+
+You need a warehouse to proceed.
+
+- **If the user specified a warehouse** (by name or UUID), use it.
+- **If not:** call `analyze_storage_costs` with no `warehouse_id`. The tool will either auto-pick when only one supported warehouse exists, or return a list of supported warehouses — let the user choose one, then call the tool again with the chosen `warehouse_id`.
+
+### Step 2: Run the analysis
+
+Call `analyze_storage_costs` with:
+
+- `warehouse_id`: the warehouse UUID
+
+The tool fetches candidates, classifies them into waste patterns (Unread, Write-only, Dead-end, Static waste, Zombie, Other stale) and table categories (Temporary, Archive/Snapshot, Production, Other), computes safety tiers, and returns a formatted analysis.
+
+- If the tool returns an error, report it to the user and stop.
+- If no candidates are found, tell the user and stop.
+
+### Step 3: Present the initial summary
+
+The tool output contains two regions:
+
+1. A `<!-- PRESENT_AS_IS -->` block with a condensed summary, a Top-N table, and a drill-down prompt.
+2. A `<!-- CATEGORY_DETAILS -->` block with per-category tables wrapped in `<!-- CATEGORY:<key> -->` markers. Do NOT present these yet.
+
+Present ONLY the `<!-- PRESENT_AS_IS -->` block — copy it verbatim, preserving every column, row, and value. Add a brief intro sentence if needed, then paste the block unchanged. The user will see the summary and top tables, then choose a category to drill into.
+
+**CRITICAL — do NOT call any other tool after `analyze_storage_costs` succeeds.** No `search`, no `get_table`, no troubleshooting agents, no cross-checks. The analysis result IS the final answer; your only remaining job is to present the `<!-- PRESENT_AS_IS -->` block verbatim.
+
+**CRITICAL — preserve markdown-linked MCONs verbatim.** The pre-formatted tables already contain properly linked MCONs (e.g., `` [`db:schema.table`](https://getmontecarlo.com/assets/MCON++...) ``). Never output bare MCON strings as plain text.
+
+### Step 4: Handle follow-up requests
+
+**Category drill-downs.** When the user asks about a specific category ("show me temporary tables", "what about production?", "tell me more about archive"):
+
+1. Find the matching `<!-- CATEGORY:<key> -->` section in the `analyze_storage_costs` result already in the conversation. **Do NOT re-invoke `analyze_storage_costs`** — the data is already there.
+2. Present that section's content verbatim — every column, row, and value.
+3. After presenting, remind the user of remaining categories they haven't explored yet.
+
+Category keywords (see `references/output-structure.md` for the full list):
+
+- "temporary", "staging", "tmp", "stg" → `CATEGORY:temporary`
+- "archive", "snapshot", "backup", "old" → `CATEGORY:archive_snapshot`
+- "uncategorized", "other", "unknown" → `CATEGORY:other`
+- "production", "prod", "critical", "important" → `CATEGORY:production`
+
+If the user says "show me everything" or "all categories", present all category sections in order: temporary → archive → uncategorized → production.
+
+**Lineage checks.** When the user asks what consumes a specific table ("check lineage for X", "is it safe to remove Y?", "what depends on this table?"):
+
+1. Call `get_asset_lineage` with `mcons: [<table mcon>]` and `direction: "DOWNSTREAM"`.
+2. If `has_relationships: false` → the table's consumers are likely BI dashboards or tools (not other tables). Mention this — it may still be safe to remove, but the user should verify with dashboard owners.
+3. If downstream tables exist AND are also stale → recommend removing both.
+4. If downstream tables are active → flag as risky, do NOT recommend removal.
+
+**Note:** The `N consumers` flag in the Usage & Risk column counts ALL consumers, including BI dashboards (Looker, Tableau, Power BI) and other non-table assets. The lineage tool only returns table-to-table edges, so lineage results may show fewer consumers than the count. When that happens, explain the gap to the user.
+
+## Reading the Usage & Risk column
+
+Each row's final `Usage & Risk` cell combines read-side activity with risk flags. Format:
+
+```
+{activity}                          # no flags fire
+{activity}; {flag1, flag2, ...}     # one or more flags fire
+```
+
+**Activity values** (always present):
+
+- `No reads` -- no recorded reads
+- `180d · 0 reads` -- last read N days ago, zero total reads
+- `2d · 580 reads / 14 users` -- recent reads, total reads and distinct reading users
+
+A low `days since read` is only meaningful when paired with the read count — a single backup job or security scanner can make a cold table look "1d". Always weigh staleness against reads + users.
+
+**Risk flags** (appended after `; ` in this fixed order when any fire):
+
+- `high criticality` / `medium criticality` -- pre-computed criticality
+- `N consumers` -- has active consumers (tables, views, or BI dashboards); verify before removing
+- `high importance score` -- `is_important` is a thresholded `importance_score ≥ 0.6` computed upstream in Databricks, **not** a user-applied tag
+- `has monitors` -- actively monitored by Monte Carlo
+
+## Table categories
+
+Tables are automatically classified for prioritized review:
+
+- **Temporary/Staging** -- Short-lived ETL/test tables (safest to drop)
+- **Archive/Snapshot** -- Historical copies, date-suffixed tables (verify retention policies)
+- **Production** -- Monitored, critical, or lineage-important tables (highest risk)
+- **Other** -- No strong signal either way (needs manual review)
+
+## Scope limitations
+
+- **Storage** costs only -- not compute, query optimization, or billing
+- One warehouse per analysis
+- **Snowflake, BigQuery, Redshift, and Databricks** only
+- **Recommendations only** -- never execute DROP TABLE or destructive actions
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.