Skip to content

Commit d27adec

Browse files
iamontheinetiamontheinet
committed
Add claude-cortex-code-router in new agent-to-agent-skills directory
New top-level directory for skills that enable AI agents to delegate work to other agents. First skill routes Snowflake tasks from Claude Code to Cortex Code CLI with security envelopes (RO/RW/RESEARCH/DEPLOY). - Clean rewrite of sfc-gh-tjia claude_skill_cortexcode concept - SKILL.md, scripts (discover + execute), README with attribution - Update install_skills.sh: new category, description, path routing - Update install.ps1: PowerShell fallback includes new category - Update generate-skills-table.sh: scans agent-to-agent-skills/ - Update root README: link + Browse Skills reference - Install agent rule files for Claude, Cursor, Windsurf, Gemini - Gitignore transient freshness report, re-seed doc hash baseline
1 parent c44096f commit d27adec

15 files changed

Lines changed: 1397 additions & 6 deletions

File tree

‎.claude/rules/claude-cortex-code-router.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
name: claude-cortex-code-router
3+
description: "Route Snowflake operations from Claude Code to Cortex Code CLI for specialized expertise. Use for: Snowflake queries via Cortex, delegate to Cortex Code, Cortex Code headless, multi-agent Snowflake workflow. Triggers: cortex code, delegate to cortex, route to cortex, use cortex for snowflake, snowflake specialist."
4+
---
5+
6+
# Claude-to-Cortex Code Router
7+
8+
Delegate Snowflake-specific operations from Claude Code to Cortex Code CLI, which has deep Snowflake expertise (dynamic tables, semantic views, data quality, Cortex AI, cost optimization, and 30+ specialized skills).
9+
10+
## When to Use
11+
12+
- User explicitly asks to delegate a task to Cortex Code
13+
- User wants Snowflake-specific expertise that Cortex Code excels at (semantic views, data quality DMFs, Cortex Agents, cost analysis, ML pipelines)
14+
- User is in Claude Code but needs Cortex Code's specialized Snowflake skills
15+
- User mentions "use Cortex Code" or "route to Cortex"
16+
17+
**Do NOT use when:**
18+
- Task is general programming (Python, JS, web dev)
19+
- Task involves non-Snowflake databases
20+
- Task is local file editing, git operations, or infrastructure work
21+
- User hasn't indicated they want Cortex Code involvement
22+
23+
## Tools Used
24+
25+
- `bash` — Run `cortex` CLI and helper scripts
26+
- `ask_user_question` — Confirm security envelope and connection
27+
- `read` — Load script files from this skill's `scripts/` directory
28+
29+
## Bundled Files
30+
31+
```
32+
claude-cortex-code-router/
33+
├── SKILL.md # This file (agent instructions)
34+
├── README.md # Human-facing docs
35+
└── scripts/
36+
├── execute_cortex.py # Headless Cortex CLI invocation
37+
└── discover_cortex.py # Enumerate available Cortex skills
38+
```
39+
40+
## Stopping Points
41+
42+
- Phase 0: User approves the delegation workflow
43+
- Step 2: User confirms security envelope before execution
44+
45+
---
46+
47+
## Phase 0: Briefing and Consent
48+
49+
Present the following briefing to the user:
50+
51+
> ### Cortex Code Router — What This Skill Does
52+
>
53+
> I'll delegate your Snowflake task to Cortex Code, which runs as a
54+
> specialized agent with deep Snowflake expertise.
55+
>
56+
> **How it works:**
57+
> ```
58+
> Your request → Claude Code (this session)
59+
> → Cortex Code CLI (headless, auto-approval)
60+
> → Snowflake execution (SQL, tools, skills)
61+
> → Results returned here
62+
> ```
63+
>
64+
> **What Cortex Code brings:**
65+
> - 30+ specialized Snowflake skills (data quality, semantic views, cost intelligence, etc.)
66+
> - Native `snowflake_sql_execute` and `data_diff` tools
67+
> - Snowflake-specific training and documentation awareness
68+
>
69+
> **Requires:** Cortex Code CLI installed and a configured Snowflake connection
70+
>
71+
> **Security:** You choose a security envelope (read-only, read-write, etc.)
72+
> that controls what tools Cortex can use.
73+
74+
**⚠️ MANDATORY STOPPING POINT**: Do NOT proceed until user explicitly approves.
75+
76+
---
77+
78+
## Step 1: Discover Cortex Capabilities (Optional)
79+
80+
Run the discovery script to enumerate what Cortex Code can do:
81+
82+
```bash
83+
python3 <skill_dir>/scripts/discover_cortex.py
84+
```
85+
86+
This caches Cortex's bundled skills to `/tmp/cortex-capabilities.json`. If it fails
87+
(Cortex not installed, etc.), continue without it — the skill still works.
88+
89+
Use the discovered capabilities to inform the user what Cortex can help with.
90+
91+
---
92+
93+
## Step 2: Choose Security Envelope
94+
95+
Ask the user which security envelope to use:
96+
97+
| Envelope | What Cortex Can Do | Blocked Tools |
98+
|----------|-------------------|---------------|
99+
| **RO** (Read-Only) | Queries, reads, exploration | Edit, Write, destructive Bash |
100+
| **RW** (Read-Write) | SQL DDL/DML, file creation | Destructive Bash (rm -rf, sudo) |
101+
| **RESEARCH** | Read + web search | Write operations |
102+
| **DEPLOY** | Full access | Nothing (use cautiously) |
103+
104+
Default to **RW** for most Snowflake operations. Use **RO** for pure queries.
105+
106+
**⚠️ MANDATORY STOPPING POINT**: Confirm envelope with the user before executing.
107+
108+
---
109+
110+
## Step 3: Build Enriched Prompt
111+
112+
Construct a prompt for Cortex that includes:
113+
114+
1. **The user's request** — the Snowflake task to perform
115+
2. **Relevant context** — any database, schema, table names, or constraints from the current conversation
116+
3. **Specific instructions** — e.g., "Use the data-quality skill" or "Run this SQL"
117+
118+
Format:
119+
```
120+
# Context from Current Session
121+
[Relevant conversation details — database names, schemas, prior results]
122+
123+
# Task
124+
[User's original request, rephrased for clarity if needed]
125+
```
126+
127+
Keep context concise — Cortex starts a fresh session each invocation.
128+
129+
---
130+
131+
## Step 4: Execute via Cortex Code
132+
133+
Run the execution script:
134+
135+
```bash
136+
python3 <skill_dir>/scripts/execute_cortex.py \
137+
--prompt "ENRICHED_PROMPT_HERE" \
138+
--envelope RW \
139+
--connection CONNECTION_NAME
140+
```
141+
142+
Arguments:
143+
- `--prompt` (required): The enriched prompt from Step 3
144+
- `--envelope` (default: RW): Security envelope from Step 2
145+
- `--connection` (optional): Snowflake connection name (uses default if omitted)
146+
147+
The script:
148+
1. Invokes `cortex -p "..." --output-format stream-json --input-format stream-json`
149+
2. The `--input-format stream-json` flag enables programmatic mode (auto-approval of tool calls)
150+
3. Security is enforced via `--disallowed-tools` based on the chosen envelope
151+
4. Parses the NDJSON event stream and returns structured results
152+
153+
---
154+
155+
## Step 5: Return Results
156+
157+
Parse the JSON output from `execute_cortex.py` and present to the user:
158+
159+
- **Text responses**: Display Cortex's analysis or explanation
160+
- **SQL results**: Format query output as tables
161+
- **Errors**: Surface any failures with actionable guidance
162+
- **Tool calls**: Summarize what Cortex did (which tools it used, what SQL it ran)
163+
164+
If the result is incomplete or needs follow-up, you can run Step 4 again with additional context.
165+
166+
---
167+
168+
## Common Issues
169+
170+
| Issue | Solution |
171+
|-------|----------|
172+
| `cortex: command not found` | Install Cortex Code CLI: `curl -LsS https://ai.snowflake.com/static/cc-scripts/install.sh \| sh` |
173+
| `No Snowflake connection configured` | Run `cortex connections create` to set up a connection |
174+
| Permission denied despite correct envelope | Check that `--disallowed-tools` isn't blocking the needed tool; try a less restrictive envelope |
175+
| Cortex hangs or times out | The `--input-format stream-json` flag auto-approves tools; if it still hangs, check network connectivity to Snowflake |
176+
| `python3: No module found` | Scripts use stdlib only — ensure Python 3.8+ is installed |
177+
178+
## Output
179+
180+
- Cortex Code execution results (SQL output, analysis, generated code) surfaced in Claude Code
181+
- Full transparency of tool calls made by Cortex
182+
- Structured JSON for programmatic consumption
183+
184+
## References
185+
186+
- [Cortex Code CLI docs](https://docs.snowflake.com/en/user-guide/cortex-code/cortex-code-cli)
187+
- [Original inspiration: sfc-gh-tjia/claude_skill_cortexcode](https://github.com/sfc-gh-tjia/claude_skill_cortexcode) — the multi-agent routing pattern this skill is based on

‎.cursor/rules/claude-cortex-code-router.mdc‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
name: claude-cortex-code-router
3+
description: "Route Snowflake operations from Claude Code to Cortex Code CLI for specialized expertise. Use for: Snowflake queries via Cortex, delegate to Cortex Code, Cortex Code headless, multi-agent Snowflake workflow. Triggers: cortex code, delegate to cortex, route to cortex, use cortex for snowflake, snowflake specialist."
4+
---
5+
6+
# Claude-to-Cortex Code Router
7+
8+
Delegate Snowflake-specific operations from Claude Code to Cortex Code CLI, which has deep Snowflake expertise (dynamic tables, semantic views, data quality, Cortex AI, cost optimization, and 30+ specialized skills).
9+
10+
## When to Use
11+
12+
- User explicitly asks to delegate a task to Cortex Code
13+
- User wants Snowflake-specific expertise that Cortex Code excels at (semantic views, data quality DMFs, Cortex Agents, cost analysis, ML pipelines)
14+
- User is in Claude Code but needs Cortex Code's specialized Snowflake skills
15+
- User mentions "use Cortex Code" or "route to Cortex"
16+
17+
**Do NOT use when:**
18+
- Task is general programming (Python, JS, web dev)
19+
- Task involves non-Snowflake databases
20+
- Task is local file editing, git operations, or infrastructure work
21+
- User hasn't indicated they want Cortex Code involvement
22+
23+
## Tools Used
24+
25+
- `bash` — Run `cortex` CLI and helper scripts
26+
- `ask_user_question` — Confirm security envelope and connection
27+
- `read` — Load script files from this skill's `scripts/` directory
28+
29+
## Bundled Files
30+
31+
```
32+
claude-cortex-code-router/
33+
├── SKILL.md # This file (agent instructions)
34+
├── README.md # Human-facing docs
35+
└── scripts/
36+
├── execute_cortex.py # Headless Cortex CLI invocation
37+
└── discover_cortex.py # Enumerate available Cortex skills
38+
```
39+
40+
## Stopping Points
41+
42+
- Phase 0: User approves the delegation workflow
43+
- Step 2: User confirms security envelope before execution
44+
45+
---
46+
47+
## Phase 0: Briefing and Consent
48+
49+
Present the following briefing to the user:
50+
51+
> ### Cortex Code Router — What This Skill Does
52+
>
53+
> I'll delegate your Snowflake task to Cortex Code, which runs as a
54+
> specialized agent with deep Snowflake expertise.
55+
>
56+
> **How it works:**
57+
> ```
58+
> Your request → Claude Code (this session)
59+
> → Cortex Code CLI (headless, auto-approval)
60+
> → Snowflake execution (SQL, tools, skills)
61+
> → Results returned here
62+
> ```
63+
>
64+
> **What Cortex Code brings:**
65+
> - 30+ specialized Snowflake skills (data quality, semantic views, cost intelligence, etc.)
66+
> - Native `snowflake_sql_execute` and `data_diff` tools
67+
> - Snowflake-specific training and documentation awareness
68+
>
69+
> **Requires:** Cortex Code CLI installed and a configured Snowflake connection
70+
>
71+
> **Security:** You choose a security envelope (read-only, read-write, etc.)
72+
> that controls what tools Cortex can use.
73+
74+
**⚠️ MANDATORY STOPPING POINT**: Do NOT proceed until user explicitly approves.
75+
76+
---
77+
78+
## Step 1: Discover Cortex Capabilities (Optional)
79+
80+
Run the discovery script to enumerate what Cortex Code can do:
81+
82+
```bash
83+
python3 <skill_dir>/scripts/discover_cortex.py
84+
```
85+
86+
This caches Cortex's bundled skills to `/tmp/cortex-capabilities.json`. If it fails
87+
(Cortex not installed, etc.), continue without it — the skill still works.
88+
89+
Use the discovered capabilities to inform the user what Cortex can help with.
90+
91+
---
92+
93+
## Step 2: Choose Security Envelope
94+
95+
Ask the user which security envelope to use:
96+
97+
| Envelope | What Cortex Can Do | Blocked Tools |
98+
|----------|-------------------|---------------|
99+
| **RO** (Read-Only) | Queries, reads, exploration | Edit, Write, destructive Bash |
100+
| **RW** (Read-Write) | SQL DDL/DML, file creation | Destructive Bash (rm -rf, sudo) |
101+
| **RESEARCH** | Read + web search | Write operations |
102+
| **DEPLOY** | Full access | Nothing (use cautiously) |
103+
104+
Default to **RW** for most Snowflake operations. Use **RO** for pure queries.
105+
106+
**⚠️ MANDATORY STOPPING POINT**: Confirm envelope with the user before executing.
107+
108+
---
109+
110+
## Step 3: Build Enriched Prompt
111+
112+
Construct a prompt for Cortex that includes:
113+
114+
1. **The user's request** — the Snowflake task to perform
115+
2. **Relevant context** — any database, schema, table names, or constraints from the current conversation
116+
3. **Specific instructions** — e.g., "Use the data-quality skill" or "Run this SQL"
117+
118+
Format:
119+
```
120+
# Context from Current Session
121+
[Relevant conversation details — database names, schemas, prior results]
122+
123+
# Task
124+
[User's original request, rephrased for clarity if needed]
125+
```
126+
127+
Keep context concise — Cortex starts a fresh session each invocation.
128+
129+
---
130+
131+
## Step 4: Execute via Cortex Code
132+
133+
Run the execution script:
134+
135+
```bash
136+
python3 <skill_dir>/scripts/execute_cortex.py \
137+
--prompt "ENRICHED_PROMPT_HERE" \
138+
--envelope RW \
139+
--connection CONNECTION_NAME
140+
```
141+
142+
Arguments:
143+
- `--prompt` (required): The enriched prompt from Step 3
144+
- `--envelope` (default: RW): Security envelope from Step 2
145+
- `--connection` (optional): Snowflake connection name (uses default if omitted)
146+
147+
The script:
148+
1. Invokes `cortex -p "..." --output-format stream-json --input-format stream-json`
149+
2. The `--input-format stream-json` flag enables programmatic mode (auto-approval of tool calls)
150+
3. Security is enforced via `--disallowed-tools` based on the chosen envelope
151+
4. Parses the NDJSON event stream and returns structured results
152+
153+
---
154+
155+
## Step 5: Return Results
156+
157+
Parse the JSON output from `execute_cortex.py` and present to the user:
158+
159+
- **Text responses**: Display Cortex's analysis or explanation
160+
- **SQL results**: Format query output as tables
161+
- **Errors**: Surface any failures with actionable guidance
162+
- **Tool calls**: Summarize what Cortex did (which tools it used, what SQL it ran)
163+
164+
If the result is incomplete or needs follow-up, you can run Step 4 again with additional context.
165+
166+
---
167+
168+
## Common Issues
169+
170+
| Issue | Solution |
171+
|-------|----------|
172+
| `cortex: command not found` | Install Cortex Code CLI: `curl -LsS https://ai.snowflake.com/static/cc-scripts/install.sh \| sh` |
173+
| `No Snowflake connection configured` | Run `cortex connections create` to set up a connection |
174+
| Permission denied despite correct envelope | Check that `--disallowed-tools` isn't blocking the needed tool; try a less restrictive envelope |
175+
| Cortex hangs or times out | The `--input-format stream-json` flag auto-approves tools; if it still hangs, check network connectivity to Snowflake |
176+
| `python3: No module found` | Scripts use stdlib only — ensure Python 3.8+ is installed |
177+
178+
## Output
179+
180+
- Cortex Code execution results (SQL output, analysis, generated code) surfaced in Claude Code
181+
- Full transparency of tool calls made by Cortex
182+
- Structured JSON for programmatic consumption
183+
184+
## References
185+
186+
- [Cortex Code CLI docs](https://docs.snowflake.com/en/user-guide/cortex-code/cortex-code-cli)
187+
- [Original inspiration: sfc-gh-tjia/claude_skill_cortexcode](https://github.com/sfc-gh-tjia/claude_skill_cortexcode) — the multi-agent routing pattern this skill is based on

0 commit comments

Comments
 (0)