cortex-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cortex Code Integration Skill

Cortex Code集成技能

Install

安装

bash

undefined

bash

undefined

Install via npm skills ecosystem (works with Claude Code, Cursor, Codex, and 40+ agents)

通过npm技能生态安装（兼容Claude Code、Cursor、Codex及40+种Agent）

npx skills add snowflake-labs/subagent-cortex-code --copy

Prerequisite: Cortex Code CLI must be installed and configured

前置条件：必须已安装并配置Cortex Code CLI

See: https://docs.snowflake.com/en/user-guide/cortex-code

参考文档：https://docs.snowflake.com/en/user-guide/cortex-code

which cortex # verify installation


This skill enables your coding agent to leverage Cortex Code's specialized Snowflake expertise by intelligently routing Snowflake-related operations to Cortex Code CLI in headless mode.

which cortex # 验证安装状态


该技能可让你的编码Agent以无头模式将Snowflake相关操作智能路由至Cortex Code CLI，从而利用其专业的Snowflake技术能力。

Architecture Overview

架构概述

Routing Principle: ONLY Snowflake operations → Cortex Code. Everything else → your coding agent.

Key Components:

Dynamic skill discovery at session initialization
LLM-based semantic routing (not keyword matching)
Security wrapper with approval modes (prompt/auto/envelope_only)
Stateless Cortex execution with context enrichment
Hybrid memory management
Audit logging for compliance

路由原则：仅Snowflake操作→Cortex Code。其他所有操作→你的编码Agent。

核心组件:

会话初始化时的动态技能发现
基于LLM的语义路由（非关键词匹配）
带有审批模式的安全包装器（prompt/auto/envelope_only）
上下文增强的无状态Cortex执行
混合内存管理
合规性审计日志

Security

安全机制

The skill includes a security wrapper around Cortex execution with three approval modes:

该技能在Cortex执行环节包含安全包装器，提供三种审批模式：

Approval Modes

审批模式

prompt (default): High security
- User shown approval prompt with predicted tools and confidence
- User must approve before execution
- No audit logging required
- Best for: Interactive sessions, untrusted prompts, production
auto: Medium security
- All operations auto-approved
- Mandatory audit logging
- Envelopes still enforced
- Best for: Automated workflows, trusted environments
envelope_only: Medium security
- No tool prediction (faster)
- Auto-approved with audit logging
- Relies on envelope blocklist only
- Best for: Trusted environments, low latency needs

Configuration: Set in

config.yaml

in the skill's install directory, or via organization policy.

prompt（默认）：高安全性
- 向用户展示包含预测工具及置信度的审批提示
- 执行前需用户手动批准
- 无需审计日志
- 适用场景：交互式会话、不可信提示、生产环境
auto：中等安全性
- 所有操作自动批准
- 强制启用审计日志
- 仍会执行信封限制
- 适用场景：自动化工作流、可信环境
envelope_only：中等安全性
- 不进行工具预测（速度更快）
- 自动批准并记录审计日志
- 仅依赖信封黑名单
- 适用场景：可信环境、低延迟需求

配置方式：在技能安装目录的

config.yaml

中设置，或通过组织策略配置。

Built-in Protections

内置防护措施

Prompt Sanitization: Automatic PII removal and injection detection
Credential Blocking: Prevents routing when credential paths detected
Secure Caching: SHA256-validated cache in
```
~/.cache/cortex-skill/
```
Audit Logging: Structured JSONL logs (mandatory for auto/envelope_only)

Organization Policy: Enterprise override via

~/.snowflake/cortex/claude-skill-policy.yaml

提示内容清理：自动移除PII信息并检测注入攻击
凭证拦截：检测到凭证路径时阻止路由
安全缓存：在
```
~/.cache/cortex-skill/
```
中存储经SHA256验证的缓存
审计日志：结构化JSONL日志（auto/envelope_only模式强制启用）

组织策略：通过

~/.snowflake/cortex/claude-skill-policy.yaml

进行企业级覆盖

Session Initialization

会话初始化

When this skill is first loaded:

首次加载该技能时：

Step 1: Discover Cortex Capabilities

步骤1：发现Cortex能力

bash

python scripts/discover_cortex.py

This script:

Runs
```
cortex skill list
```
to enumerate all available Cortex skills
Reads each skill's SKILL.md frontmatter and trigger patterns
Caches capabilities in
```
/tmp/cortex-capabilities.json
```
for this session
Returns structured data about what Cortex can handle

Expected output: JSON mapping of skill names to their trigger patterns and capabilities.

bash

python scripts/discover_cortex.py

该脚本会：

运行
```
cortex skill list
```
枚举所有可用的Cortex技能
读取每个技能的SKILL.md前置信息和触发模式
将能力缓存到
```
/tmp/cortex-capabilities.json
```
供本次会话使用
返回Cortex可处理任务的结构化数据

预期输出：技能名称与其触发模式、能力的JSON映射关系。

Step 2: Load Routing Context

步骤2：加载路由上下文

The discovered capabilities are loaded into memory to inform routing decisions throughout the session.

将发现的能力加载至内存，为整个会话的路由决策提供依据。

Workflow: Handling User Requests

工作流程：处理用户请求

Step 1: Analyze Request with LLM-Based Routing

步骤1：基于LLM分析请求并路由

Before taking any action, analyze the user's request:

bash

python scripts/route_request.py --prompt "USER_PROMPT_HERE"

This script:

Loads Cortex capabilities from cache
Uses LLM reasoning to classify the request
Returns routing decision with confidence score

Routing Logic:

Route to Cortex if request involves:
- Snowflake databases, warehouses, schemas, tables
- SQL queries specifically for Snowflake
- Cortex AI features (Cortex Search, Cortex Analyst, ML functions)
- Snowpark, dynamic tables, streams, tasks
- Data governance, data quality, or security in Snowflake context
- User explicitly mentions "Cortex" or "Snowflake"
Route to your coding agent if request involves:
- Local file operations (reading, writing, editing local files)
- General programming (Python, JavaScript, etc. not Snowflake-specific)
- Non-Snowflake databases (PostgreSQL, MySQL, MongoDB, etc.)
- Web development, frontend work
- Infrastructure/DevOps unrelated to Snowflake
- Git operations, GitHub, version control

在执行任何操作前，先分析用户请求：

bash

python scripts/route_request.py --prompt "USER_PROMPT_HERE"

该脚本会：

从缓存加载Cortex能力
使用LLM推理对请求进行分类
返回带有置信度分数的路由决策

路由逻辑:

路由至Cortex的场景：
- Snowflake数据库、数据仓库、模式、表相关操作
- 针对Snowflake的SQL查询
- Cortex AI功能（Cortex Search、Cortex Analyst、ML函数）
- Snowpark、动态表、流、任务
- Snowflake语境下的数据治理、数据质量或安全相关操作
- 用户明确提及“Cortex”或“Snowflake”
路由至编码Agent的场景：
- 本地文件操作（读取、写入、编辑本地文件）
- 通用编程（非Snowflake相关的Python、JavaScript等）
- 非Snowflake数据库（PostgreSQL、MySQL、MongoDB等）
- Web开发、前端工作
- 与Snowflake无关的基础设施/DevOps任务
- Git操作、GitHub、版本控制

Step 2: Execute Based on Routing Decision

步骤2：根据路由决策执行

If routing is

coding_agent

(handle locally):

若路由至

coding_agent

（本地处理）：

Handle the request directly using your agent's built-in capabilities. No Cortex involvement.

直接使用Agent的内置能力处理请求，无需Cortex参与。

If routed to Cortex Code:

若路由至Cortex Code：

Proceed to Step 3.

进入步骤3。

Step 3: Choose Security Envelope and Handle Approval

步骤3：选择安全信封并处理审批

Before executing Cortex, the security wrapper handles approval based on configured mode.

执行Cortex前，安全包装器会根据配置的模式处理审批流程。

Step 3a: Check Approval Mode

步骤3a：检查审批模式

Read configuration to determine approval behavior:

prompt mode (default): Requires user approval
auto mode: Auto-approve with audit logging
envelope_only mode: Auto-approve, no tool prediction

读取配置确定审批行为：

prompt模式（默认）：需要用户批准
auto模式：自动批准并记录审计日志
envelope_only模式：自动批准，不进行工具预测

Step 3b: Handle Approval (if prompt mode)

步骤3b：处理审批（prompt模式下）

If using prompt mode:

bash

python scripts/security_wrapper.py \
  --prompt "ENRICHED_PROMPT" \
  --envelope "RW"

This will:

Predict required tools using LLM

Display approval prompt to user:

Cortex Code needs to execute the following tools:

  • snowflake_sql_execute
  • Read
  • Write

Envelope: RW
Confidence: 85%

Approve execution? [yes/no]

If approved, proceed to Step 3c
If denied, abort execution

若使用prompt模式：

bash

python scripts/security_wrapper.py \
  --prompt "ENRICHED_PROMPT" \
  --envelope "RW"

该命令会：

使用LLM预测所需工具

向用户展示审批提示：

Cortex Code需要执行以下工具：

  • snowflake_sql_execute
  • Read
  • Write

安全信封：RW
置信度：85%

是否批准执行？[yes/no]

若批准，进入步骤3c
若拒绝，终止执行

Step 3c: Determine Security Envelope

步骤3c：确定安全信封

Determine the appropriate security envelope based on the operation:

RO (Read-Only): For queries and read operations - blocks Edit, Write, destructive Bash
RW (Read-Write): For data modifications - allows most operations, blocks destructive Bash
RESEARCH: For exploratory work - read access plus web tools
DEPLOY: For full access - no blocklist (use cautiously)
NONE: Custom blocklist via --disallowed-tools

根据操作类型选择合适的安全信封：

RO（只读）：用于查询和读取操作 - 阻止编辑、写入、破坏性Bash命令
RW（读写）：用于数据修改 - 允许大多数操作，阻止破坏性Bash命令
RESEARCH（研究）：用于探索性工作 - 读取权限加网络工具
DEPLOY（部署）：完全访问权限 - 无黑名单（谨慎使用）
NONE（自定义）：通过--disallowed-tools指定自定义黑名单

Step 4: Enrich Context for Cortex

步骤4：为Cortex增强上下文

Build an enriched prompt that includes:

Claude Conversation Context:

Last 2-3 relevant exchanges from current Claude session
Any Snowflake-specific details already discussed

Recent Cortex Session Context:

bash

python scripts/read_cortex_sessions.py --limit 3

This reads the most recent Cortex session files from

~/.local/share/cortex/sessions/

to understand what Cortex recently worked on.

Enriched Prompt Format:

undefined

构建包含以下内容的增强提示：

Claude会话上下文:

当前Claude会话中最近2-3次相关对话
已讨论过的任何Snowflake特定细节

近期Cortex会话上下文:

bash

python scripts/read_cortex_sessions.py --limit 3

该脚本读取

~/.local/share/cortex/sessions/

中最近的Cortex会话文件，了解Cortex近期处理的任务。

增强提示格式:

undefined

Context from Current Session

当前会话上下文

[Recent relevant conversation history]

[近期相关对话历史]

Recent Cortex Work

Cortex近期工作内容

[Summary from recent Cortex sessions]

[近期Cortex会话摘要]

User Request

用户请求

[Original user prompt]

undefined

[原始用户提示]

undefined

Step 5: Execute Cortex Code Headlessly

步骤5：无头模式执行Cortex Code

bash

python scripts/execute_cortex.py \
  --prompt "ENRICHED_PROMPT" \
  --connection "connection_name" \
  --envelope "RW" \
  --disallowed-tools "tool1" "tool2"

This script:

Invokes

cortex -p "prompt" --output-format stream-json --bypass

Uses
```
--bypass
```
for headless auto-approval without interactive stdin
Applies envelope-based security via
```
--disallowed-tools
```
blocklist for safety
Parses NDJSON event stream in real-time
Detects tool use events and execution results

Key Insight:

--bypass

puts Cortex in headless mode where all tool calls auto-execute without interactive permission prompts. This works for both built-in and non-builtin tools (snowflake_sql_execute, data_diff, MCP tools, etc.) without a TTY or stdin. Note:

--input-format stream-json

does NOT work for headless execution — it hangs waiting for stdin in non-TTY environments.

Security Envelopes:

RO (Read-Only): Blocks Edit, Write, destructive Bash commands
RW (Read-Write): Blocks destructive operations like rm -rf, sudo
RESEARCH: Read access plus web tools, blocks write operations
DEPLOY: Full access with no blocklist
NONE: Custom blocklist via --disallowed-tools parameter

Event Stream Handling:

```
type: assistant
```
→ Cortex's responses, display to user
```
type: tool_use
```
→ Cortex is calling a tool
```
type: result
```
→ Final outcome

bash

python scripts/execute_cortex.py \
  --prompt "ENRICHED_PROMPT" \
  --connection "connection_name" \
  --envelope "RW" \
  --disallowed-tools "tool1" "tool2"

该脚本会：

调用

cortex -p "prompt" --output-format stream-json --bypass

使用
```
--bypass
```
实现无头自动批准，无需交互式标准输入
通过
```
--disallowed-tools
```
黑名单应用基于信封的安全限制
实时解析NDJSON事件流
检测工具使用事件和执行结果

关键提示：

--bypass

将Cortex置于无头模式，所有工具调用自动执行，无需交互式权限提示。该模式适用于内置工具和非内置工具（snowflake_sql_execute、data_diff、MCP工具等），无需TTY或标准输入。注意：

--input-format stream-json

不适用于无头执行——在非TTY环境中会因等待标准输入而挂起。

安全信封说明:

RO（只读）：阻止编辑、写入、破坏性Bash命令
RW（读写）：阻止rm -rf、sudo等破坏性操作
RESEARCH（研究）：读取权限加网络工具，阻止写入操作
DEPLOY（部署）：完全访问权限，无黑名单
NONE（自定义）：通过--disallowed-tools参数指定自定义黑名单

事件流处理:

```
type: assistant
```
→ Cortex的响应，展示给用户
```
type: tool_use
```
→ Cortex正在调用工具
```
type: result
```
→ 最终执行结果

Step 6: Handle Permission Requests

步骤6：处理权限请求

With the security wrapper:

prompt mode: User approves BEFORE execution (no mid-execution prompts)
auto/envelope_only modes: All tools auto-approved via
```
--bypass
```
flag

The security wrapper handles permission management through:

Upfront approval (prompt mode): User approves predicted tools before execution
Audit logging (auto/envelope_only): All operations logged to
```
audit.log
```
in the skill's install directory
Envelope enforcement: Tool blocklist still enforced via
```
--disallowed-tools
```

通过安全包装器：

prompt模式：用户在执行前批准（无执行中提示）
auto/envelope_only模式：通过
```
--bypass
```
标志自动批准所有工具

安全包装器通过以下方式管理权限：

预先批准（prompt模式）：用户在执行前批准预测的工具
审计日志（auto/envelope_only模式）：所有操作记录到技能安装目录的
```
audit.log
```
信封强制：仍通过
```
--disallowed-tools
```
执行工具黑名单限制

Step 7: Return Results to User

步骤7：向用户返回结果

Format Cortex's output for the current session:

Show SQL query results in readable format
Display any generated artifacts
Report success/failure status
Provide relevant excerpts from Cortex's analysis

为当前会话格式化Cortex的输出：

以可读格式展示SQL查询结果
显示生成的任何工件
报告成功/失败状态
提供Cortex分析中的相关摘录

Examples

示例

Example 1: Snowflake Query

示例1：Snowflake查询

User says: "Show me the top 10 customers by revenue in Snowflake"

Routing: → Cortex Code (Snowflake SQL query)

Security Envelope: RW (allows SQL execution)

Cortex Action:

Uses snowflake_sql_execute to run:

SELECT customer_name, SUM(revenue) as total FROM sales GROUP BY customer_name ORDER BY total DESC LIMIT 10

Returns formatted results

Result: Table displayed to user with top 10 customers.

用户请求："在Snowflake中展示收入最高的前10位客户"

路由：→ Cortex Code（Snowflake SQL查询）

安全信封：RW（允许SQL执行）

Cortex操作:

使用snowflake_sql_execute执行：

SELECT customer_name, SUM(revenue) as total FROM sales GROUP BY customer_name ORDER BY total DESC LIMIT 10

返回格式化结果

结果：向用户展示包含前10位客户的表格。

Example 2: Local File Operation

示例2：本地文件操作

User says: "Read the config.json file in this directory"

Routing: → your coding agent (local file operation)

Claude Action: Uses Read tool directly, no Cortex involvement.

Result: File contents displayed.

用户请求："读取当前目录下的config.json文件"

路由：→ 你的编码Agent（本地文件操作）

Claude操作：直接使用Read工具，无需Cortex参与。

结果：展示文件内容。

Example 3: Data Quality Check

示例3：数据质量检查

User says: "Check data quality for the SALES_DATA table"

Routing: → Cortex Code (Snowflake data quality - matches Cortex's data-quality skill)

Security Envelope: RW (allows SQL execution for analysis)

Cortex Action:

Runs data quality checks using its data-quality skill
Analyzes schema, null rates, duplicates, etc.
Generates quality report

Result: Comprehensive data quality report with recommendations.

用户请求："检查SALES_DATA表的数据质量"

路由：→ Cortex Code（Snowflake数据质量 - 匹配Cortex的data-quality技能）

安全信封：RW（允许执行分析用SQL）

Cortex操作:

使用其data-quality技能运行数据质量检查
分析模式、空值率、重复数据等
生成质量报告

结果：提供包含建议的全面数据质量报告。

Important Notes

重要说明

Security Wrapper

安全包装器

The skill uses a security wrapper that provides:

Approval modes: prompt (default), auto, envelope_only
Prompt sanitization: Automatic PII removal and injection detection
Credential blocking: Prevents routing when credential paths detected
Audit logging: Mandatory for auto/envelope_only modes
Tool prediction: LLM predicts required tools for approval prompt

Configuration:

config.yaml

in the skill's install directory, or via organization policy

该技能使用的安全包装器提供：

审批模式：prompt（默认）、auto、envelope_only
提示内容清理：自动移除PII信息并检测注入攻击
凭证拦截：检测到凭证路径时阻止路由
审计日志：auto/envelope_only模式强制启用
工具预测：LLM预测所需工具用于审批提示

配置：技能安装目录的

config.yaml

，或通过组织策略配置

Headless Execution with Auto-Approval

无头自动批准执行

When using auto or envelope_only modes:

All tool calls are automatically approved without interactive prompts
Works for built-in tools (Read, Write, Edit, Bash, Grep, Glob) and non-builtin tools (snowflake_sql_execute, data_diff, MCP tools)
Uses
```
--bypass
```
flag for non-TTY headless execution (stdin is ignored)
Security is controlled via
```
--disallowed-tools
```
blocklist instead of interactive approval

使用auto或envelope_only模式时：

所有工具调用自动批准，无需交互式提示
适用于内置工具（Read、Write、Edit、Bash、Grep、Glob）和非内置工具（snowflake_sql_execute、data_diff、MCP工具）
使用
```
--bypass
```
标志实现非TTY无头执行（忽略标准输入）
通过
```
--disallowed-tools
```
黑名单而非交互式批准控制安全

Stateless Execution

无状态执行

Each Cortex invocation is stateless. Context must be explicitly provided via enriched prompts.

每次Cortex调用都是无状态的。必须通过增强提示明确提供上下文。

Memory Boundaries

内存边界

Your coding agent maintains: Full conversation history, user preferences, project context
Cortex Code receives: Only task-specific context for current operation
Cortex sessions are read: For historical context enrichment only

你的编码Agent维护：完整对话历史、用户偏好、项目上下文
Cortex Code接收：仅当前操作的任务特定上下文
Cortex会话仅用于读取：仅用于历史上下文增强

Security Envelope Strategy

安全信封策略

Choose envelopes based on operation risk:

Start with RO or RW: Most operations fit here
Use RESEARCH: When web access is needed for exploratory work
Use DEPLOY: Only for operations requiring full access (e.g., git push, sudo)
Use NONE with custom blocklist: When fine-grained control is needed

根据操作风险选择信封：

优先使用RO或RW：大多数操作适用
使用RESEARCH：需要网络访问的探索性工作
使用DEPLOY：仅用于需要完全访问权限的操作（如git push、sudo）
使用NONE加自定义黑名单：需要细粒度控制时

Performance Considerations

性能注意事项

Cortex skill discovery runs once per session (cached)
Each Cortex execution adds ~2-5 seconds latency
Use routing wisely to minimize unnecessary Cortex calls

Cortex技能发现每个会话运行一次（已缓存）
每次Cortex执行增加约2-5秒延迟
合理使用路由以减少不必要的Cortex调用

Troubleshooting

故障排除

Error: "Cortex CLI not found"

错误："Cortex CLI not found"

Cause: Cortex Code is not installed or not in PATH

Solution:

bash

which cortex

原因：Cortex Code未安装或未在PATH中

解决方案:

bash

which cortex

If not found, check installation: ~/.snowflake/cortex/

若未找到，检查安装路径：~/.snowflake/cortex/

undefined

undefined

Error: Approval prompt not appearing (or appearing unexpectedly)

错误：审批提示未出现（或意外出现）

Cause: Approval mode misconfiguration or organization policy override

Solution:

bash

undefined

原因：审批模式配置错误或组织策略覆盖

解决方案:

bash

undefined

Check approval mode (path varies by agent: ~/.claude/, ~/.cursor/, ~/.codex/, etc.)

检查审批模式（路径因Agent而异：/.claude/、/.cursor/、~/.codex/等）

cat "$(dirname $(which cortex))/../skills/cortex-code/config.yaml" | grep approval_mode 2>/dev/null
|| cat ~/skills/cortex-code/config.yaml | grep approval_mode

Check organization policy (overrides user config)

检查组织策略（覆盖用户配置）

cat ~/.snowflake/cortex/claude-skill-policy.yaml 2>/dev/null

Expected:

预期值:

prompt = shows approval prompts (default)

prompt = 显示审批提示（默认）

auto = auto-approves all operations

auto = 自动批准所有操作

envelope_only = auto-approves, no tool prediction

envelope_only = 自动批准，不进行工具预测

undefined

undefined

Error: "Prompt contains credential file path"

错误："Prompt contains credential file path"

Cause: Prompt mentions paths matching credential allowlist (e.g., ~/.ssh/, .env)

Solution:

Remove credential references from prompt
Or customize allowlist in config.yaml if false positive

原因：提示中提及匹配凭证白名单的路径（如~/.ssh/、.env）

解决方案:

从提示中移除凭证引用
若为误报，在config.yaml中自定义白名单

Error: PII removed from prompts

错误：提示中的PII信息被移除

Symptom: Emails, phone numbers replaced with placeholders

Cause: Automatic sanitization enabled by default

Solution: Disable if needed (not recommended):

yaml

security:
  sanitize_conversation_history: false

症状：电子邮件、电话号码被替换为占位符

原因：默认启用自动清理功能

解决方案：如有需要可禁用（不推荐）：

yaml

security:
  sanitize_conversation_history: false

Error: "Permission denied" despite auto mode

错误：即使在auto模式下仍显示"Permission denied"

Cause: Tool is in the --disallowed-tools blocklist for current envelope

Solution:

Check which envelope is being used (RO/RW/RESEARCH/DEPLOY)
If operation is safe, switch to a less restrictive envelope
Or use envelope="NONE" with custom --disallowed-tools list

原因：工具在当前信封的--disallowed-tools黑名单中

解决方案:

检查当前使用的信封（RO/RW/RESEARCH/DEPLOY）
若操作安全，切换至限制较少的信封
或使用envelope="NONE"并指定自定义--disallowed-tools列表

Error: Audit log not created

错误：未创建审计日志

Symptom: No audit.log despite auto/envelope_only mode

Solution:

bash

undefined

症状：即使在auto/envelope_only模式下也无audit.log

解决方案:

bash

undefined

Create the skill's install directory if missing and set permissions

若技能安装目录缺失则创建并设置权限

Path is agent-specific: ~/.claude/skills/cortex-code/, ~/.cursor/skills/cortex-code/, etc.

路径因Agent而异：/.claude/skills/cortex-code/、/.cursor/skills/cortex-code/等

chmod 700 "$(cd "$(dirname "$0")/.." && pwd)"

Verify audit_log_path in config.yaml within the skill directory

验证技能目录中config.yaml的audit_log_path配置

grep audit_log_path config.yaml

undefined

grep audit_log_path config.yaml

undefined

Error: Tools still requiring approval

错误：工具仍需要批准

Cause: Missing

--bypass

flag or approval_mode not set to

auto

envelope_only

Solution: Ensure

--output-format stream-json --bypass

are both present. The

--bypass

flag is what enables headless auto-approval mode. The security wrapper handles this automatically. Note:

--input-format stream-json

does NOT work — it hangs in non-TTY environments.

原因：缺少

--bypass

标志或approval_mode未设置为

auto

envelope_only

解决方案：确保同时存在

--output-format stream-json --bypass

。

--bypass

标志是启用无头自动批准模式的关键。安全包装器会自动处理此设置。注意：

--input-format stream-json

不可用——在非TTY环境中会挂起。

Issue: Routing sends Snowflake query to your coding agent

问题：Snowflake查询被路由至编码Agent

Cause: Routing logic didn't detect Snowflake keywords

Solution:

Check if user mentioned "Snowflake" explicitly
Review routing script logic in
```
scripts/route_request.py
```
Add more trigger patterns to routing context

原因：路由逻辑未检测到Snowflake关键词

解决方案:

检查用户是否明确提及"Snowflake"
查看
```
scripts/route_request.py
```
中的路由脚本逻辑
为路由上下文添加更多触发模式

Issue: Cortex returns "Connection refused"

问题：Cortex返回"Connection refused"

Cause: Snowflake connection not configured in Cortex

Solution:

bash

cortex connections list

原因：Cortex中未配置Snowflake连接

解决方案:

bash

cortex connections list

Verify connection is active

验证连接是否活跃

Check ~/.snowflake/cortex/settings.json for cortexAgentConnectionName

检查~/.snowflake/cortex/settings.json中的cortexAgentConnectionName

undefined

undefined

Issue: Context enrichment too large

问题：上下文增强内容过大

Cause: Including too much conversation history

Solution: Limit to last 2-3 relevant exchanges, summarize older context.

原因：包含过多对话历史

解决方案：限制为最近2-3次相关对话，对较早的上下文进行摘要。

Advanced: Custom Routing Rules

进阶：自定义路由规则

To customize routing beyond default logic, edit

scripts/route_request.py

python

undefined

要在默认逻辑之外自定义路由，编辑

scripts/route_request.py

python

undefined

Add custom patterns

添加自定义模式

FORCE_CORTEX_PATTERNS = [ "snowflake", "cortex", "warehouse", "snowpark" ]

FORCE_CLAUDE_PATTERNS = [ "local file", "git commit", "python script" # unless Snowpark ]

undefined

FORCE_CORTEX_PATTERNS = [ "snowflake", "cortex", "warehouse", "snowpark" ]

FORCE_CLAUDE_PATTERNS = [ "local file", "git commit", "python script" # 除非是Snowpark相关 ]

undefined

References

参考资料

See

references/

directory for:

```
cortex-cli-reference.md
```
- Full Cortex CLI documentation
```
routing-examples.md
```
- More routing decision examples
```
session-file-format.md
```
- Cortex session file structure
```
troubleshooting-guide.md
```
- Extended troubleshooting

查看

references/

目录获取：

```
cortex-cli-reference.md
```
- 完整Cortex CLI文档
```
routing-examples.md
```
- 更多路由决策示例
```
session-file-format.md
```
- Cortex会话文件结构
```
troubleshooting-guide.md
```
- 扩展故障排除指南

cortex-code

Original

Translation

Cortex Code Integration Skill

Cortex Code集成技能

Install

安装

Install via npm skills ecosystem (works with Claude Code, Cursor, Codex, and 40+ agents)

通过npm技能生态安装（兼容Claude Code、Cursor、Codex及40+种Agent）

Prerequisite: Cortex Code CLI must be installed and configured

前置条件：必须已安装并配置Cortex Code CLI

See: https://docs.snowflake.com/en/user-guide/cortex-code

参考文档：https://docs.snowflake.com/en/user-guide/cortex-code

Architecture Overview

架构概述

Security

安全机制

Approval Modes

审批模式

Built-in Protections

内置防护措施

Session Initialization

会话初始化

Step 1: Discover Cortex Capabilities

步骤1：发现Cortex能力

Step 2: Load Routing Context

步骤2：加载路由上下文

Workflow: Handling User Requests

工作流程：处理用户请求

Step 1: Analyze Request with LLM-Based Routing

步骤1：基于LLM分析请求并路由

Step 2: Execute Based on Routing Decision

步骤2：根据路由决策执行

If routing is coding_agent (handle locally):

若路由至coding_agent（本地处理）：

If routed to Cortex Code:

若路由至Cortex Code：

Step 3: Choose Security Envelope and Handle Approval

步骤3：选择安全信封并处理审批

Step 3a: Check Approval Mode

步骤3a：检查审批模式

Step 3b: Handle Approval (if prompt mode)

步骤3b：处理审批（prompt模式下）

Step 3c: Determine Security Envelope

步骤3c：确定安全信封

Step 4: Enrich Context for Cortex

步骤4：为Cortex增强上下文

Context from Current Session

当前会话上下文

Recent Cortex Work

Cortex近期工作内容

User Request

用户请求

Step 5: Execute Cortex Code Headlessly

步骤5：无头模式执行Cortex Code

Step 6: Handle Permission Requests

步骤6：处理权限请求

Step 7: Return Results to User

步骤7：向用户返回结果

Examples

示例

Example 1: Snowflake Query

示例1：Snowflake查询

Example 2: Local File Operation

示例2：本地文件操作

Example 3: Data Quality Check

示例3：数据质量检查

Important Notes

重要说明

Security Wrapper

安全包装器

Headless Execution with Auto-Approval

无头自动批准执行

Stateless Execution

无状态执行

Memory Boundaries

内存边界

Security Envelope Strategy

安全信封策略

Performance Considerations

If routing is
`coding_agent`
(handle locally):

若路由至
`coding_agent`
（本地处理）：