AutoGineer
Generated banner for Cortex Router
Generated logo for Cortex Router

Cortex Router

SnowflakeOfficialCreated by Snowflake Integration Team

  • Skill
  • Tool integration
  • Automation and integrations
  • Apache-2.0
  • No issues found
Download ZIP

From the author

Auto-routing skill loaded by the prompt filter hook. Routes Snowflake-related operations to Cortex Code CLI. Not for direct invocation — use $cortex-run instead.
— the description by Snowflake Integration Team

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The cortex-router is a background utility designed to intercept user prompts and determine whether they should be handled by the standard Claude Code environment or routed to the specialized Cortex Code CLI. It ensures that Snowflake-specific operations—such as data quality checks, ML model creation, governance tasks, and dynamic table management—are processed by the appropriate toolset. The router manages the lifecycle of these requests, including CLI verification, session persistence for multi-turn conversations, and security envelope enforcement.

What it does

  • Verifies the installation and configuration of the Cortex Code CLI.
  • Analyzes user prompts to determine if they require Snowflake-specific capabilities.
  • Routes requests to the Cortex Code CLI with appropriate security envelopes (RO, RW, RESEARCH, DEPLOY).
  • Maintains multi-turn conversation context using session IDs and the resume-last flag.
  • Handles routing failures by reporting errors rather than bypassing configuration policies.
  • Formats and presents output from Cortex operations back to the user.

When to use it

  • When you need to perform Snowflake-specific operations like data governance or ML tasks.
  • When working with Snowflake dynamic tables or specialized Cortex AI features.
  • When you need to maintain context across multiple turns for a Snowflake-related data analysis task.
  • When you are unsure if a query should be handled by standard SQL tools or specialized Cortex skills.

Advantages

  • Ensures specialized Snowflake skills are utilized for relevant tasks.
  • Provides seamless multi-turn interaction by persisting session context.
  • Enforces security by applying specific execution envelopes to operations.
  • Reduces ambiguity by providing a structured decision tree for routing requests.

Usage examples

“Show me all tables in my Snowflake database”
The router identifies the explicit Snowflake mention and routes the request to the Cortex Code CLI for execution.
“Check data quality for my orders table”
The router detects a match for the Cortex data-quality skill and initiates the request via the Cortex CLI.
“drill into the top customer”
The router uses the --resume-last flag to maintain context from the previous Cortex turn, allowing for a deeper analysis.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/snowflake-labs/cortex-router/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip cortex-router.zip -d .agents/skills

Documentation by Snowflake Integration Team

Cortex Code Router

Route Snowflake operations to Cortex Code CLI, which has specialized bundled skills (data-quality, semantic-view, cost-intelligence, ML, governance, etc.).

CRITICAL: Follow steps 1 → 2 → 3 in order. Do NOT skip to Step 3.

Step 1: Verify CLI

which cortex 2>/dev/null && cortex --version

If cortex is NOT found:

  1. Tell the user: "Cortex Code CLI is not installed. Setting it up now."

  2. Load the snowflake-cortex-code:cortex-setup skill using the Skill tool.

  3. STOP — do not continue until the CLI is installed.

Step 2: Confirm Routing

Run the routing script to check if this prompt should go to Cortex or stay in Claude Code:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/run_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/router/route_request.py" --prompt "USER_PROMPT_HERE"

Replace USER_PROMPT_HERE with the actual user prompt (shell-escaped).

The shared launcher selects python3, or python only after verifying Python 3. Use Bash (Git Bash on Windows). It never retries a failed script under another interpreter. If routing fails, STOP and report the error; do not bypass a configuration/policy error.

Read the output carefully:

  • If output says "route: cortex" → proceed to Step 3

  • If output says "route: claude" → STOP. Handle the request yourself using Claude Code tools (sql_execute, Read, Write, etc.). Do NOT run execute_cortex.py.

Step 3: Execute via Cortex Code

Only reach this step if Step 2 confirmed routing to Cortex.

Choose a security envelope based on the operation:

  • RO: Read-only queries (SELECT, SHOW, DESCRIBE) — won't run DDL or DML

  • RW: Data modifications, DDL (CREATE, ALTER, DROP) — default for most operations

  • RESEARCH: Read + web access, no writes

  • DEPLOY: Full access (use sparingly)

Default to RW unless the request is clearly read-only.

bash "${CLAUDE_PLUGIN_ROOT}/scripts/run_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/router/execute_cortex.py" \
  --prompt "USER_PROMPT_HERE" \
  --envelope "RW"

Add --connection CONNECTION_NAME if a specific Snowflake connection is needed.

Multi-turn: --resume-last vs fresh

Every cortex invocation returns a session_id that the router persists. Follow-up turns can resume that session so Cortex sees the prior conversation -- real multi-turn, not one-shot batches per prompt.

  • Add --resume-last when the current prompt is a continuation of the previous Cortex turn: "keep going", "apply the top suggestion", "dig deeper", "also show me ...", "and for last quarter", "fix that", or any clarification of an answer Cortex just gave.

  • Omit --resume-last (start fresh) when the user switches topics, asks about a different database/warehouse, or begins a clearly new task.

  • --resume <session_id> is also accepted if you have an explicit id.

# Follow-up on the previous Cortex turn
bash "${CLAUDE_PLUGIN_ROOT}/scripts/run_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/router/execute_cortex.py" \
  --prompt "drill into the top customer" --envelope "RO" \
  --resume-last

Timeout: This command may take 30-90 seconds. If it takes longer than 2 minutes, it likely hung — kill the process and tell the user to try $cortex-run for direct invocation.

Step 4: Return Results

Format Cortex's output for the user:

  • Show SQL results in readable tables

  • Display any generated artifacts or analysis

  • Report success/failure clearly

Notes

  • Cortex has bundled skills for: data-quality, semantic-view, cost-intelligence, ML, governance, security, lineage, dynamic-tables, and more

  • For simple SQL queries that don't need Cortex skills, Step 2 should route to Claude Code

  • If routing or execution fails, STOP and report the error rather than bypassing the plugin

  • Multi-turn context is preserved across invocations via --resume-last (see Step 3)

Files

references/cortex-cli-reference.md

Cortex CLI Reference

Core Commands

Headless Execution
cortex -p "your prompt here" --output-format stream-json

Executes Cortex in headless mode with streaming JSON output.

Output Format: NDJSON (newline-delimited JSON)

  • Each line is a complete JSON object

  • Events stream in real-time as they occur

Permission Management
cortex -p "prompt" --allowed-tools "tool1" "tool2" "tool3"

Explicitly allows specific tools. Required for headless execution when --dangerously-allow-all-tool-calls is disabled by organization.

Skill Discovery
cortex skill list

Lists all available skills (bundled and custom).

Connection Management
cortex connections list

Shows all configured Snowflake connections.

Search Operations
cortex search object <pattern>
cortex search docs <query>

Searches Snowflake objects or documentation.

Event Stream Types

System Events
{
  "type": "system",
  "subtype": "init",
  "session_id": "unique-session-id",
  "tools": ["read", "write", "bash", ...],
  "model": "auto"
}

Initialization event at session start.

Assistant Events
{
  "type": "assistant",
  "session_id": "...",
  "message": {
    "role": "assistant",
    "content": [
      {"type": "text", "text": "Response here"},
      {"type": "tool_use", "id": "...", "name": "bash", "input": {...}}
    ]
  }
}

Cortex's responses and tool invocations.

User Events
{
  "type": "user",
  "session_id": "...",
  "message": {
    "role": "user",
    "content": [
      {"type": "tool_result", "tool_use_id": "...", "content": "result or error"}
    ]
  }
}

Tool results or user input (including permission denials).

Result Events
{
  "type": "result",
  "session_id": "...",
  "subtype": "success",
  "result": "Final outcome text",
  "is_error": false,
  "duration_ms": 5234,
  "num_turns": 3
}

Final session result.

Permission Denials

When a tool is not in --allowed-tools, you'll see:

{
  "type": "user",
  "message": {
    "content": [{
      "type": "tool_result",
      "tool_use_id": "toolu_xxx",
      "content": "Permission denied: Tool denied: headless mode requires --allowed-tools"
    }]
  }
}

Handling:

  1. Detect permission denial in event stream

  2. Extract the requested tool from the context

  3. Surface to user via Claude Code's AskUserQuestion

  4. Re-invoke Cortex with updated --allowed-tools if approved

Available Tools in Cortex

  • snowflake_sql_execute - Execute SQL queries on Snowflake

  • bash - Run bash commands

  • read - Read files

  • write - Write files

  • edit - Edit files

  • glob - File pattern matching

  • grep - Content search

  • web_fetch - Fetch web content

  • ask_user_question - Ask user questions

  • task - Task management

  • Plus skill-specific tools

Common Patterns

Simple Query
cortex -p "Show top 10 customers" \
  --output-format stream-json \
  --allowed-tools "snowflake_sql_execute" "bash"
Data Quality Check
cortex -p "Check data quality for my orders table" \
  --output-format stream-json \
  --allowed-tools "snowflake_sql_execute" "bash" "read" "write"
With Context Enrichment
cortex -p "# Previous Context
User asked about customer segmentation.

# Recent Cortex Work
Ran RFM analysis on customers table.

# Current Request
Create a dynamic table for high-value customers" \
  --output-format stream-json \
  --allowed-tools "snowflake_sql_execute" "bash" "read"

Configuration Files

Settings Location

~/.snowflake/cortex/settings.json

Key settings:

  • cortexAgentConnectionName - Default Snowflake connection

  • model - AI model to use

  • Other Cortex-specific preferences

Trust Settings

~/.snowflake/cortex/cortex.json

Project-specific trust and permissions.

Session Files

~/.local/share/cortex/sessions/*.jsonl

Stored session transcripts for context enrichment.

Error Handling

Connection Errors
Error: Connection refused

Solution: Check Snowflake connection:

cortex connections list
Tool Permission Errors
Permission denied: Tool denied: headless mode requires --allowed-tools

Solution: Add tool to --allowed-tools list.

Model Errors
Error: Rate limit exceeded

Solution: Cortex routes through Snowflake Cortex AI. Check Snowflake quotas.

Best Practices

  1. Start Conservative: Begin with minimal tool set, expand as needed

  2. Enrich Context: Always provide relevant background from Claude session

  3. Read Sessions: Check recent Cortex work to avoid duplicate operations

  4. Handle Streams: Parse NDJSON line-by-line, don't wait for completion

  5. Timeout Handling: Set reasonable timeouts (30-60s for complex queries)

  6. Error Recovery: Detect permission denials early, prompt user immediately

Limitations

  • No Persistent Sessions: Each invocation is stateless

  • No --resume: Session resumption not available in headless mode

  • Organization Policies: Some flags may be blocked (e.g., --bypass, --dangerously-allow-all-tool-calls)

  • Tool Restrictions: Only tools in --allowed-tools can be used

  • Rate Limits: Subject to Snowflake Cortex AI rate limits

Requirements and compatibility

Written for: Claude Code

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Claude Code frontmatter, Needs Python

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Snowflake Integration Team
Publisher
Snowflake (Official)
Source
Snowflake-Labs/snowflake-ai-kit · plugins/cortex-code/skills/cortex-router · commit 6a9165f
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Snowflake Integration Team or Snowflake.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download cortex-router.zip