Supercharge Cortex Code CLI - A Practical Guide to Skills, SubAgents, Hooks and MCP

Introduction

I was originally a Cursor user for AI-assisted coding. But as someone who works with Snowflake data and features daily, I realized how powerful it is to have an AI agent that natively connects to Snowflake's data, functions, and catalog — living right in your terminal. That's when I made Cortex Code CLI (CoCo CLI for short) my primary tool.

As I used CoCo CLI more, I wanted an agent that could work more autonomously. CoCo CLI offers extensive customization capabilities, and I've gone deep — defining 7 custom skills, 5 custom subagents, quality-check hooks with Slack notifications, and MCP integrations with external tools. The result has been a dramatic improvement in my day-to-day productivity.

This article won't cover CoCo CLI basics or installation — for those, check out the official documentation. Instead, I'll dive into the 4 extensibility features (Skills, SubAgents, Hooks, MCP) and AGENTS.md, sharing tips from the official docs combined with practical insights from my own experience.

Note: This article contains many opinions based on my personal experience. This is not an official Snowflake statement, and customization methods or best practices may change with future updates.

The Big Picture of CoCo CLI Extensibility

CoCo CLI customization breaks down into two categories:

• AGENTS.md — A Markdown file placed at the project root that communicates project-specific rules and constraints to the agent (Official docs: Cortex Code)
• 4 Extensibility Features — Mechanisms documented on the official Extensibility page that extend the agent's capabilities

Here's a summary of each feature's role:

Feature	Role	Scope	Format
AGENTS.md	Communicate project-specific rules & constraints	Project	Markdown
Skills	Inject domain-specific expertise & workflows	Project / Global	YAML frontmatter + Markdown
SubAgents	Delegate tasks to independent specialized agents	Project / Global	YAML frontmatter + Markdown
Hooks	Intercept lifecycle events for custom control	Project / Global	JSON + Shell scripts
MCP	Add external tool & service integrations	Global	JSON

Let's explore each feature in detail.

AGENTS.md — Injecting Project Rules

Overview

AGENTS.md is a Markdown file placed at the project root that communicates project-specific rules and coding conventions to the CoCo CLI agent. (Official docs: Cortex Code)

AGENTS.md is separate from the 4 extensibility features (Skills, SubAgents, Hooks, MCP) on the Extensibility page. While extensibility features extend the agent's capabilities, AGENTS.md defines the agent's behavioral guidelines.

Attribute	Details
Location	Project root directory
Format	Free-form Markdown
Loading	Auto-loaded at session start
Effect	Improves agent response quality & consistency

Basic Usage

Simply create an AGENTS.md file in your project root:

# Project Rules

## Coding Standards
- Follow Black formatter for Python code style
- Always include type hints
- Use Google-style docstrings

## Snowflake-Specific Rules
- Write SQL in uppercase
- Use full paths for table names: `DB.SCHEMA.TABLE`
- Use `MY_WH` warehouse

## Testing
- Run tests with pytest: `pytest tests/ -v`
- Maintain 80%+ coverage

Tip: Adding AGENTS.md dramatically improves agent responses. For team development, documenting coding standards and project rules in AGENTS.md ensures consistent AI-assisted quality across all team members.

Effective AGENTS.md Structure

Here's the structure pattern I use in practice:

# Project Overview
(Brief description of purpose and architecture)

# Directory Structure
(Key directories and file roles)

# Tech Stack
(Languages, frameworks, tools)

# Coding Standards (Do)
(Style guide, naming conventions, comment policy)

# Don'ts
(Secrets handling, destructive SQL prohibition, direct production access ban)

# Snowflake-Specific Settings
(Connection info, default warehouse/role, naming conventions)

# Testing & Quality
(Test commands, lint commands, CI/CD notes)

# Custom Skills & SubAgents Guide
(Names and purposes of custom skills/subagents used in the project)

TIPS: Making AGENTS.md Work Effectively

AGENTS.md can also be placed at .cortex/AGENTS.md or in subdirectories, and you can use multiple files. However, keep these points in mind:

• AGENTS.md is an Instruction at the start of task execution. Writing too many rules tends to dilute compliance. Focus on high-priority items and keep it concise.
• Explicit Do / Don't sections are effective. Clearly separating "what to do" from "what not to do" improves the agent's decision accuracy.
• Include directory structure. Documenting your project's folder structure helps the agent choose appropriate file locations.
• Add a custom skills/subagents guide. Listing names, purposes, and invocation methods of your custom skills/subagents helps the agent use them at the right time.

Important: AGENTS.md is just an Instruction — there's no guarantee the agent will always follow it. For higher compliance rates, clear and concise writing is key. To enforce rules, consider using Hooks (e.g., PreToolUse to block dangerous operations).

Since CoCo CLI is natively integrated with Snowflake, leveraging Snowflake governance features like RBAC (roles), masking policies, and Row Access Policies for data access control is highly effective. Rather than writing "don't directly modify production tables" in AGENTS.md, simply restricting write permissions via roles is far more reliable. Soft guidelines in AGENTS.md, hard enforcement via Hooks and Snowflake governance — this separation is another strength of CoCo CLI.

Skills — Injecting Domain Knowledge

Official docs: Extensibility - Skills

Overview

Skills are Markdown files that define domain-specific expertise and workflows, injected into the agent's context when needed. For example, "demo environment setup procedures," "periodic report creation workflows," or "PoC documentation templates" — by defining frequently-used business workflows as skills, you eliminate the need to instruct from scratch every time.

There are 2 ways to invoke skills:

1. Explicit invocation — Use the $skill-name prefix to directly specify a skill
2. Automatic activation — The agent matches your question against skill description fields and auto-loads relevant skills

Many built-in skills have a [REQUIRED] tag, causing them to activate automatically when questions hit their domain. For instance, simply typing "I want to create a Dynamic Table pipeline" automatically loads the dynamic-tables skill with specialized guidance.

Skill Locations

Skills are loaded from multiple locations (highest to lowest priority). (Official docs: Extensibility)

Scope	Path	Description
Project	.cortex/skills/ or .claude/skills/	Project-specific
User	~/.snowflake/cortex/skills/ or ~/.claude/skills/	User-specific
Global	~/.snowflake/cortex/skills/	Shared across all projects
Session	Added temporarily during session	Disappears when session ends
Remote	Cloned from Git repository	Cached
Bundled	Built into CoCo CLI	Official Snowflake skills

Custom skill creation directories are also documented as .cortex/commands/ or .claude/commands/.

Creating SKILL.md

Skills are Markdown files named SKILL.md with YAML frontmatter at the top:

---
name: my-custom-skill
description: "Description of this skill (shown in skill listings)"
tools:
  - snowflake_sql_execute
  - snowflake_object_search
  - web_search
---

# Purpose
(What this skill does)

# Prerequisites
(Required environment/data for execution)

# Workflow
1. Step 1: ...
2. Step 2: ...
3. Step 3: ...

# Output
(Expected deliverables)

Frontmatter	Required	Description
name	Yes	Unique identifier
description	Yes	Skill description (shown in /skill list)
tools	No	Tools to enable when skill is active

CLI Commands

cortex skill list
cortex skill add /path/to/.cortex/skills/my-skill
cortex skill add https://github.com/org/my-skills.git
cortex skill remove /path/to/.cortex/skills/my-skill

Invoking Skills in a Session

There are two main approaches — explicit invocation and automatic activation:

Method	Action	Description
Skill listing	Type /skill or $ in session	Shows available skill candidates
Explicit invocation	$skill-name instruction	Loads the specified skill and executes the task
Auto-activation	Just ask your question normally	Agent auto-selects skills matching the description

$demo-builder Set up a demo environment
$code-review Review @src/app.py following $security-guidelines

For auto-activation, you don't need to specify skill names. Many built-in skills have [REQUIRED] tags and automatically load when relevant domain questions are asked.

> I want to create a Streamlit app
→ developing-with-streamlit skill auto-activates

> Analyze my costs
→ cost-intelligence skill auto-activates

Tip: Use cortex skill list from outside a session to check available skills. Before creating custom skills, explore what's already built-in.

Built-in Skills

CoCo CLI ships with 33 built-in skills covering major Snowflake capabilities (as of v1.0.45). From data engineering to governance, ML, and cost analysis — everything is ready out of the box, making it one of CoCo CLI's biggest strengths.

Category	Skills
Data Foundation	dynamic-tables, iceberg, lineage, data-quality
Development	developing-with-streamlit, build-react-app, snowpark-python, snowpark-connect, snowflake-notebooks, dbt-projects-on-snowflake
AI / ML	cortex-agent, cortex-ai-functions, semantic-view, machine-learning
Governance / Security	data-governance, trust-center, network-security, key-and-secret-management
Operations / Cost	cost-intelligence, workload-performance-analysis, organization-management
Data Sharing	data-cleanrooms, declarative-sharing, internal-marketplace-org-listing
Infrastructure	deploy-to-spcs, integrations, openflow, snowflake-postgres
Migration / Admin	snowconvert-assessment, dcm, dashboard, skill-development, cortex-code-guide

Built-in skills may change with CoCo CLI version updates. The above list is as of v1.0.45. Check the latest with cortex skill list.

Practical Example: Demo Environment Builder Skill

Here's an example skill for building customer demo environments:

---
name: demo-builder
description: "Build and clean up Snowflake demo environments"
tools:
  - snowflake_sql_execute
  - snowflake_object_search
  - web_search
---

# Demo Builder Skill

## Goal
Build and manage Snowflake demo environments tailored to
customer use cases, in a reproducible manner.

## Workflow
### Phase 1: Requirements
Confirm demo theme, target features, and required datasets.

### Phase 2: Environment Setup
Create DB/schema/warehouse, load sample data,
deploy Streamlit apps as needed.

### Phase 3: Verification
Test all queries/apps and create demo scenarios.

### Phase 4: Cleanup
Generate scripts to safely tear down the environment post-demo.

With this skill defined, simply invoking $demo-builder Set up a Cortex AI demo kicks off the entire workflow automatically.

SubAgents — Specialized Agent Delegation

Official docs: Extensibility - Subagents

Overview

SubAgents are independent, specialized AI agents that operate separately from the main agent. Each can have its own model, tools, and prompts, with parallel execution support.

Feature	Description
Independence	Operates in separate context from main agent
Specialization	Specify optimal model and tools per task
Parallel execution	Up to 50 concurrent agents
Worktree Isolation	Isolate changes using Git worktrees

Built-in SubAgents

CoCo CLI includes these built-in subagent types: (Official docs: Extensibility)

Type	Purpose
general-purpose	Full tool access, general-purpose agent
explore	Codebase exploration specialist (quick / medium / very thorough)
plan	Implementation planning & design
feedback	Structured feedback collection

Creating Custom SubAgents

SubAgents are defined as .md files:

Scope	Path
Project	.cortex/agents/<name>.md or .claude/agents/<name>.md
Global	~/.snowflake/cortex/agents/<name>.md
User	~/.claude/agents/<name>.md

Agent Definition Example

---
name: critic-reviewer
description: "Performs critical review from code quality and best practices perspective"
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: openai-gpt-5.2
---

# Critic Reviewer Agent

You are a senior software engineer performing code reviews.

## Review Criteria
1. Code readability & maintainability
2. Performance bottlenecks
3. Security concerns
4. Error handling adequacy

## Output Format
- 🔴 Critical: Must fix
- 🟡 Warning: Recommended fix
- 🟢 Info: Room for improvement

Model Selection — The Greatest Strength of SubAgents

Custom subagents let you specify a model per agent via the model field. This is SubAgents' greatest strength.

model: claude-opus-4-6     # For high-accuracy tasks
model: claude-sonnet-4-6   # For lightweight, fast tasks
model: openai-gpt-5.2      # Leverage different model perspectives
model: auto                # Cost-optimized auto-selection

TIPS: Cross-model diversity improves quality

When your main agent uses claude-opus-4-6, deliberately assigning openai-gpt-5.2 to your review subagent enables critical review from a different model's perspective. A different model family can catch blind spots and mistakes that the same model tends to miss.

Meanwhile, for simpler tasks like knowledge curation or log summarization, assigning a lightweight model like claude-sonnet-4-6 keeps costs down while boosting overall throughput.

Use Case	Model Selection Strategy
Main agent	High-accuracy model (claude-opus-4-6, etc.)
Critical review	Deliberately use a different model family (openai-gpt-5.2, etc.) for diverse perspectives
Knowledge curation / summarization	Lightweight model (claude-sonnet-4-6, etc.) for cost efficiency
Exploration / research	auto for cost optimization

Session-wide model can also be overridden via the CORTEX_AGENT_MODEL environment variable. (Official docs: Settings)

Invocation

# Auto-delegation (agent decides)
> Search all test files under src/

# Explicit specification
> Use the Explore agent to find all SQL files

# Parallel execution
> In parallel, search for test files and check config files

# Background execution
> Run a background agent to refactor the code

# Worktree Isolation (runs in an isolated git branch)
> Implement feature X with worktree isolation

# Agent management
/agents                    # Agent list (Ctrl-B also works)
> Get the output from agent abc1234
> kill agent abc1234
> Resume agent abc1234 and continue from where it left off

Practical Example: Specialized Agent Configuration

Here's my setup with purpose-specific agents:

Agent	Model	Purpose
critic-reviewer	openai-gpt-5.2	Critical review using a different model from main
research-analyst	auto	Web research & document analysis
code-implementer	claude-opus-4-6	Complex code implementation
qa-validator	claude-opus-4-6	Test design & execution
knowledge-curator	claude-sonnet-4-6	Knowledge organization & documentation

Hooks — Lifecycle Control

Official docs: Extensibility - Hooks

Overview

Hooks execute custom logic at key lifecycle points in CoCo CLI.

Personally, I consider Hooks the most important of the four extensibility features. As AI agents evolve, we'll increasingly delegate tasks asynchronously. But this creates common pain points:

• Unaware — The agent finishes work, but the user doesn't notice and leaves it idle
• Stuck — The agent is waiting for user input, but the user doesn't realize it's blocked
• Settling — The agent produces low-quality output and completes without improvement

Hooks address these challenges. For example:

• Send Slack notifications on Notification events so you never miss an input request or completion
• Run quality checks on Stop events and force the agent to continue if results don't meet standards

Hooks have many configuration options and may require some trial-and-error to get the behavior you want. But they're incredibly powerful — I personally receive Slack notifications to issue next instructions and use quality-check hooks to force the agent to self-review and elevate output quality, achieving a truly "set it and forget it" workflow.

Configuration File Locations

Hooks are configured in the following locations (highest to lowest priority):

Scope	Path
Local (highest)	.cortex/settings.local.json or .claude/settings.local.json
Project	.cortex/settings.json or .claude/settings.json
User	~/.claude/settings.json
Global	~/.snowflake/cortex/hooks.json

Available Events

The 11 hook events defined in official docs:

Event	Timing	Can Block?
PreToolUse	Before tool execution	Yes
PostToolUse	After successful tool execution	No
PermissionRequest	When permission is needed	Yes
UserPromptSubmit	When user submits prompt	No
SessionStart	When session starts	No
SessionEnd	When session ends	No
PreCompact	Before context compaction	No
Stop	When agent response completes	No
SubagentStop	When subagent completes	No
Notification	On notification (e.g., waiting for user input)	No
Setup	During initialization	No

Hook Types

Two types of hooks are available: (Official docs: Extensibility)

Type	Description	Example
command	Execute shell commands	bash /path/to/script.sh
prompt	Evaluate natural language prompt via LLM	Is this command safe? $ARGUMENTS

Exit Code Semantics

Hook script exit codes control CoCo CLI behavior:

Exit Code	Meaning	Behavior
0	Success	Process stdout JSON and continue
2	Block	stderr / JSON reason sent to agent; operation blocked
Other	Error	Non-blocking. stderr shown only in verbose mode; execution continues

Configuration Format

Example hooks.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/hooks/quality_review.sh",
            "timeout": 60
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/hooks/validate_bash.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Matcher Patterns

The matcher field narrows which tools trigger hooks. Regex is supported.

Pattern	Target
*	All tools
Bash	Bash only
`Edit\	Write`
mcp__.*	All MCP tools
Notebook.*	NotebookEdit, NotebookExecute, etc.

Hook Input (stdin)

Hook scripts receive JSON via stdin:

{
  "session_id": "abc123",
  "hook_event_name": "Stop",
  "cwd": "/Users/my-project",
  "transcript_path": "/path/to/transcript.jsonl",
  "tool_name": "Bash",
  "tool_input": {
    "command": "ls -la"
  }
}

Available Environment Variables

These environment variables are available within hook scripts:

Variable	Description
CORTEX_PROJECT_DIR	Project directory path
CORTEX_CODE_REMOTE	"true" in web context
CORTEX_ENV_FILE	Persistent environment file path

Example 1: Quality Review Hook (Stop Event)

A hook that performs LLM-based quality checks when the agent tries to complete a task, blocking and continuing work if quality is insufficient:

#!/bin/bash
# quality_review_on_stop.sh

INPUT=$(cat)

# Infinite loop prevention (critical!)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi

TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path')

# Get recent interactions and run LLM quality check
REVIEW_RESULT=$(snow sql -q "
  SELECT SNOWFLAKE.CORTEX.COMPLETE(
    'claude-sonnet-4-6',
    'Rate the task completion from 1-10: ...'
  )
" --connection MY_CONN)

SCORE=$(echo "$REVIEW_RESULT" | jq -r '.score')

if [ "$SCORE" -lt 7 ]; then
  echo "Quality score below threshold ($SCORE/10). Please improve." >&2
  exit 2  # Block → agent continues working
fi

exit 0  # Allow → agent stops

Critical: Infinite loop prevention in Stop Hooks is mandatory. When a Stop Hook returns block (exit 2), the agent continues working and the Stop event fires again. Always pass through with exit 0 when the stop_hook_active flag is true.

Example 2: Slack Notification Hook (Notification Event)

A hook that sends Slack notifications when the agent is waiting for user input:

#!/bin/bash
# notify_slack_on_notification.sh

INPUT=$(cat)
MESSAGE=$(echo "$INPUT" | jq -r '.message // "Waiting for input"')

curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-type: application/json' \
  -d "{\"text\": \"🔔 Cortex Code: $MESSAGE\"}"

exit 0

MCP — External Tool Integration

Official docs: Extensibility - MCP

Overview

MCP (Model Context Protocol) is an open standard protocol for connecting external tools and services to AI agents. The key point here is that CoCo CLI itself functions as an MCP client. This means you can add any publicly available MCP server to give your agent new capabilities.

For example, draw.io MCP for diagrams, GitHub MCP for PR operations, Context7 MCP for latest library documentation — the possibilities are vast. MCP servers are growing daily, so definitely explore MCP servers and mcp.so to find servers that fit your workflow.

Transport Types

Type	Use Case	Communication
stdio	Local tools, CLI wrappers	Subprocess (stdin/stdout)
http	Web services, APIs	HTTP requests
sse	Real-time services	Server-Sent Events

OAuth authentication is supported for HTTP servers. Tokens are stored in ~/.snowflake/cortex/mcp_oauth/ and auto-refreshed.

Configuration File

MCP server configuration goes in ~/.snowflake/cortex/mcp.json:

{
  "mcpServers": {
    "drawio": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@drawio/mcp"]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Environment Variable Expansion

Both ${VAR} and $VAR syntax are supported for environment variable expansion in configuration files. (Official docs: Extensibility)

{
  "headers": {
    "Authorization": "Bearer ${MY_API_TOKEN}"
  }
}

Never hardcode API keys in mcp.json. Set them as environment variables in ~/.bashrc or ~/.zshrc like export MY_API_TOKEN="your_token_here" — this is the officially recommended approach.

CLI Commands

cortex mcp add drawio npx -y @drawio/mcp
cortex mcp add my-api https://api.example.com --type http
cortex mcp add my-server npx my-mcp-server -e API_KEY=secret
cortex mcp add my-server https://api.example.com -H "Authorization: Bearer token"
cortex mcp list
cortex mcp get drawio
cortex mcp remove drawio
cortex mcp start drawio    # Connection test

Tool Naming Convention

MCP tools are namespaced for agent access:

mcp__{server-name}__{tool-name}

e.g.: mcp__drawio__open_drawio_xml
      mcp__github__create_pull_request

Session Management

/mcp    # Open MCP status viewer

Practical Example: draw.io MCP

Adding the draw.io MCP server lets you instruct the agent to "create an architecture diagram for this design" and it generates the diagram in the draw.io editor.

cortex mcp add drawio npx -y @drawio/mcp

Usage in session:

> Create an architecture diagram for this system in draw.io

Putting It All Together

The AGENTS.md and 4 extensibility features become even more powerful when combined. Here's a workflow pattern I use daily.

Pattern: AI-Assisted Development Workflow

By combining these features:

1. AGENTS.md always applies project-specific rules
2. Skills standardize repetitive workflows
3. SubAgents process specialized tasks in parallel
4. MCP connects to external tools
5. Hooks automate quality checks and notifications on task completion

This creates a truly integrated workflow.

Configuration File Overview

Here's a partial extract of my CoCo CLI configuration structure — the actual setup has many more files, but these are the key ones. (Official docs: Settings)

~/.snowflake/cortex/
├── settings.json           # Main settings (theme, env vars, hooks)
├── mcp.json                # MCP server config
├── hooks.json              # Global hooks
├── permissions.json        # Permission settings
├── hooks/                  # Hook scripts
│   ├── quality_review_on_stop.sh
│   ├── notify_slack_on_stop.sh
│   └── ...
├── agents/                 # Custom SubAgents
│   ├── critic-reviewer.md
│   ├── research-analyst.md
│   └── ...
├── skills/                 # Global Skills
│   ├── demo-builder/SKILL.md
│   ├── competitive-analysis/SKILL.md
│   └── ...
├── memory/                 # Persistent memory
└── ...

Conclusion

Cortex Code CLI is not just an AI coding assistant — by leveraging AGENTS.md for project rules and the 4 extensibility features (Skills, SubAgents, Hooks, MCP), you can build a powerful AI development environment tailored to your workflow.

Personally, shifting from Cursor to CoCo CLI has been transformative. Being able to use customized agents while natively connected to Snowflake data and functions has dramatically improved my daily productivity. Here's what I find most valuable:

• Skills for workflow standardization: Defining repetitive workflows like demo setup and documentation as skills eliminates starting from scratch every time
• SubAgents for parallel execution: Running research tasks in parallel dramatically reduces processing time for complex tasks
• Hooks for quality gates & notifications: Auto-executing quality checks on task completion via Stop Hook and forcing continued work when quality is insufficient has been incredibly effective for raising output quality
• MCP for external tool integration: Calling external tools like draw.io and GitHub directly from the agent dramatically reduces context-switching overhead

CoCo CLI's customization features will continue to evolve. I encourage you to dive into customization and build your own AI development environment!

Reference Links

Document	URL
Cortex Code CLI official	https://docs.snowflake.com/en/user-guide/cortex-code/cortex-code-cli
Extensibility (Skills, SubAgents, Hooks, MCP)	https://docs.snowflake.com/en/user-guide/cortex-code/extensibility
Settings (Configuration & Priority)	https://docs.snowflake.com/en/user-guide/cortex-code/settings
Security	https://docs.snowflake.com/en/user-guide/cortex-code/security

Promotion

Snowflake What's New Updates on X

I share Snowflake What's New updates on X. Follow for the latest insights:

English Version

Snowflake What's New Bot (English Version)

Japanese Version

Snowflake's What's New Bot (Japanese Version)

Change Log

(20260401) Initial post

Original Japanese Article

Cortex Code CLI 実践カスタマイズガイド

zenn.dev