Cortex Code CLIの拡張性¶

スキルとは¶

スキルは、次を含むマークダウンファイルです。

• ドメイン固有の手順とベストプラクティス

• スキルを使用するタイミング

• ワークフローの例

• オプションのツール構成

ルを呼び出すと、その手順が会話コンテキストに注入されます。

スキルの使用¶

/skill list を実行して、利用可能なスキルをリストアップし、名前でスキルを呼び出して会話にロードします。

スキルの場所¶

スキルは複数の場所からロードされ、優先順位の高いものから低いものへと以下にリストされています。

カスタムスキルの作成¶

スキルは、 SKILL.md ファイルを含むディレクトリで、スキルの手順、オプションの例とテンプレートを含みます。スキルは以下のいずれかの場所で作成できます。

カスタムスキルの構築を開始するには、以下を行います。

1. スキルディレクトリを作成します。この例では、プロジェクトの場所に「my-skill」という名前のスキルディレクトリを作成します。

   CopyExpand

   mkdir -p .cortex/skills/my-skill
   

   Show lessSee more

   Scroll to top

2. このディレクトリに SKILL.md を作成し、スキルの説明を追加します。この例は基本構造を示しています。

   CopyExpand

   ---
   name: my-skill
   description: Brief description of what this skill does
   tools:
   - optional_tool_name
   ---
   
   # When to Use
   
   - Describe when this skill should be invoked
   - List specific user intents or scenarios
   
   # What This Skill Provides
   
   Explain the capabilities and knowledge this skill adds.
   
   # Instructions
   
   Step-by-step guidance for the AI when this skill is active.
   
   ## Best Practices
   
   - Best practice 1
   - Best practice 2
   
   ## Common Patterns
   
   ### Pattern 1
   Description and example.
   
   ### Pattern 2
   Description and example.
   
   # Examples
   
   ## Example 1: Basic Usage
   User: $my-skill Do something Assistant: [Expected behavior]
   
   
   ## Example 2: Advanced Usage
   User: $my-skill Complex task with @file.txt Assistant: [Expected behavior]
   

   Show lessSee more

   Scroll to top

3. $$ コマンドを使用して、スキルがリストに表示されることを確認します。

   CopyExpand

   > $$
   

   Show lessSee more

   Scroll to top

   スキルがリストされている場合は、正しくロードされ、使用可能です。

4. 会話であなたのスキルを使用します。

   CopyExpand

   > $my-skill Test it out
   

   Show lessSee more

   Scroll to top

---
name: database-admin
description: Database administration tasks
tools:
- snowflake_sql_execute
- snowflake_object_search
---

スキルの管理¶

スキルの構成¶

カスタムスキルは他のスキルを参照したり、ファイルコンテキストと権限を組み合わせることができます。

> $code-review Review @src/auth.py following $security-guidelines

リモートスキル¶

Gitリポジトリからリモートスキルを追加できます。リポジトリには任意の数のスキルを含めることができます。リモート権限のレイアウトはローカル権限の構造と一致する必要があります。

/skill add https://github.com/org/my-skills.git

リモート権限はローカルにキャッシュされます。更新するには、 /skill sync を使用します。

スキルコマンドリファレンス¶

CLI コマンド：

cortex skill list
cortex skill add <path>
cortex skill remove <path>

スラッシュコマンド：

/skill list
/skill add <path>

スキルのトラブルシューティング¶

スキルがアクティブ化しない

• スキルの目的に関連する具体的な言葉を使用

• スキルを明示的に言及します：「semantic-view-optimizationを使用する」

• 可用性を確認： /skill list

予期しない動作

• 目標についての詳細を入力してください

• より具体的なリクエストを試す

• フィードバックを送信： /feedback

組み込みサブエージェントの型¶

サブエージェントの実行¶

Cortex Codeは、必要に応じて自動的にサブエージェントに委任します。たとえば、このクエリはExploreエージェントに委任します。

> Find all files that import the authentication module

名前で特定のサブエージェントタイプを明示的にリクエストすることもできます。

> Use an Explore agent to find all database query definitions
> Use the Explore agent to find all API endpoint definitions
> Launch a Plan agent to design the authentication refactor

また、複数のサブエージェントを並行して実行し、タスクの異なる側面に取り組むようにリクエストすることもできます。

> In parallel, search for all test files and all config files

作業を続けている間、エージェントをバックグラウンドで実行できます。

> Run a background agent to refactor all the test files

エージェントはすぐに開始し、追跡用のエージェントIDを返します。エージェントが動作完了すると、IDを使用して出力を取得できます。

> Get the output from agent abc1234

実行中のすべてのサブエージェントのステータスを監視するには、 /agents コマンド（またはCtrl-Bを押し）を使用して、バックグラウンドプロセスビューアーを開きます。IDまたは /agents インターフェースを使用して、実行中のエージェントを停止できます。

> kill agent abc1234

強制終了したエージェントは実行を停止しますが、コンテキストは無期限に保持されます。IDを使用して、強制終了したエージェントを再開することができます。

> Resume agent abc1234 and continue from where it left off

エージェント型¶

自律

自律エージェントは、ユーザーの操作なしで実行されます。エージェント：

• 独立して完了

• 質問のためのブロックはありません

• 明確に定義されたタスクに適しています

非自律

非自律エージェントは、実行を一時停止してユーザーに質問することができます。エージェント：

• 明確化のための質問をする場合があります

• インタラクティブに権限をリクエストできます

• ガイダンスを必要とするタスクに適しています

カスタム

カスタムエージェントは、特殊なプロンプトと構成を持つユーザー定義のサブエージェントです。カスタムスキーマと同様に、マークダウンファイルで特定のドメインやワークフローに合わせたエージェントを作成します。

カスタムサブエージェントの作成¶

カスタムサブエージェントは、マークダウンファイルでYAMLフロントマターを使用して定義されます。フロントマターは、エージェントの名前、説明、ツールアクセス、モデルを指定します。本文には、エージェントの動作をガイドするシステムプロンプトが含まれています。

カスタムエージェントマークダウンファイルは、次の3つの場所のいずれかに保存できます。

エージェント定義の形式を次に示します。

---
name: my-agent
description: What this agent specializes in
tools:

- Bash
- Read
- Write

model: claude-sonnet-4-5
---

# System Prompt

You are a specialized agent for [domain].

## Your Responsibilities

1. Task 1
2. Task 2

## Guidelines

- Guideline 1
- Guideline 2

## Output Format

Describe expected output format.

---
name: test-runner
description: Runs tests and reports results
tools:
- Bash
- Read
- Grep
---

# Test Runner Agent

You run tests and provide clear reports of the results.

## Process

1. Identify the test framework (pytest, jest, go test, etc.)
2. Run appropriate test command
3. Parse and summarize results
4. Highlight failures with relevant code context

## Output Format

## Test Results Summary
- Total: X
- Passed: Y
- Failed: Z

## Failures
### Test Name
- File: path/to/file.py
- Error: Description
- Relevant code snippet

ワークツリーの分離¶

エージェントは、分離されたgitワークツリーまたはブランチで実行できます。ワークツリーの分離をリクエストすると、Cortex Code CLIは、エージェントが動作するための別のgitワークツリーを作成します。これにより、競合する変更なく複数のエージェントを並行して実行でき、後のクリーンアップも簡単です。分離されたワークツリーは、特に探索と実験に役立ちます。エージェントによって作成されたgitブランチの名前は agent/<agentId> です。

ワークツリーの分離を使用するには、プロンプトに含めます。

> Run a background agent with worktree isolation to implement feature X

スワームパターン¶

エージェントのワーカーを起動して、複雑なタスクのさまざまな側面に並行して対処することができます。各エージェントは独立して動作し、すべてのエージェントが終了すると結果が集約されます。すべてのタイプのエージェントはスワームに参加できます。

スワームのユースケースには次が含まれます。

• コード分析：複数のエージェントが異なる側面を分析します

• リファクタリング:並列エージェントは異なるファイルを処理します

• テスト：エージェントは異なるテストスイートを実行します

• ドキュメント：エージェントドキュメントのさまざまなコンポーネント

スワームを作成するには、起動するさまざまなエージェントを単純に記述します。

> Launch a swarm of agents:
> 1. Explore agent to find all database queries
> 2. Explore agent to find all API endpoints
> 3. Explore agent to find all test files

サブエージェントのベストプラクティス¶

次の場合にサブエージェントを使用します。

• 複雑なタスク：並列実行のためにサブタスクに分割

• 探索：コードベース検索にExploreエージェントを使用する

• 計画：大きな変更の前にPlanエージェントを使用

• バックグラウンド作業：注意の必要がない、実行時間の長いタスク

サブエージェントは次には適していません。

• 単純なクエリ：直接ツールの方が高速です

• 単一ファイルの編集：メインエージェントはより効率的です

• インタラクティブな作業：すぐにフィードバックが必要な場合

一般的に、詳細なプロンプトの方が効果的です。

アクティブなサブエージェントの表示¶

/agents コマンド

Cortex Codeセッションで /agents コマンドを発行し、インタラクティブエージェントビューアを開きます。このインターフェースは、実行中のすべてのエージェント、そのタイプ、ステータス、および出力プレビューを表示します。

バックグラウンドプロセスビューアー

Cortex Code CLIセッションで、Ctrl-Bを押して表示します。

• すべてのバックグラウンドプロセス

• エージェントセッション

• Bashプロセス

エージェントの制限¶

Cortex Code CLIのサブエージェントには以下の制限が適用されます。

• 最大50個の同時バックグラウンドエージェント

• エージェントはセッション権限を継承する

• バックグラウンドエージェントは他のバックグラウンドエージェントを生成できない

フックイベント¶

次のイベントはフックをトリガーできます。

フックの構成¶

フックは設定ファイルで構成されます。これは任意の構成ディレクトリに配置できます（優先順位の高いものから低いもの順に以下に一覧表示）。

フックはJSON形式で定義されます、イベント、ツールの一致、フックアクションを指定します。ツール使用前のフックの簡単な例を以下に示します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/validate-bash.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

コマンドフックとプロンプトフックの2つのフックタイプがサポートされています。

• コマンドフックは、シェルコマンドまたはスクリプトを実行します。

  CopyExpand

  {
    "type": "command",
    "command": "bash /path/to/script.sh",
    "timeout": 60,
    "enabled": true
  }
  

  Show lessSee more

  Scroll to top

• プロンプトフックは、言語モデルに対する自然言語プロンプトとして評価されます。

  CopyExpand

  {
    "type": "prompt",
    "prompt": "Is this command safe? $ARGUMENTS",
    "timeout": 30
  }
  

  Show lessSee more

  Scroll to top

特定のツールに対してのみフックを実行するには、 matcher フィールドにツール名またはパターンを配置します。たとえば、すべてのSQLツールをマッチするには、 "matcher": "SQL*" を使用します。正規表現を使って複数のツールにマッチさせることができます。

フックスクリプトの記述¶

フックスクリプトは標準入力を通じてJSON入力を受け入れ、標準出力を通じてJSON出力を返します。出力には、操作が許可されたか拒否されたかを示すフィールドが含まれています。オプションで、フックスクリプトはツール入力の変更バージョンを渡すことができます。

サンプル入力：

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.json",
  "cwd": "/working/directory",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "ls -la"
  }
}

サンプル出力:

{
  "decision": "allow",
  "systemMessage": "Note: This operation was validated.",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "updatedInput": {
      "command": "ls -la --color=never"
    }
  }
}

戻りコードは、操作をブロックするかどうかを示します。

• 0：ブロックしない

• 2：ブロック

この情報は、以下に示すようにJSON出力の一部として返すこともできます。

{
  "decision": "block",
  "reason": "Operation not allowed"
}

フックスクリプトでは、次の環境変数を使用できます。

フックの例¶

次の例は、一般的なフックのユースケースで可能な出力を示しています。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "updatedInput": {
      "command": "modified command"
    }
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Note: File was recently modified."
  }
}

{
  "systemMessage": "Warning: This operation may take a while."
}

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Auto-approved by policy"
  }
}

{
  "type": "command",
  "command": "bash",
  "source": {
    "source": "github:org/hooks-repo/scripts/validate.sh",
    "ref": "main"
  }
}

フックのベストプラクティス¶

• フックを高速にします：タイムアウトのデフォルトは60秒

• エラーを正常に処理します：不明な場合、exit 0を返します

• デバッグ用ログ：トラブルシューティングのためのファイルへの書き込み

• 一致を使用する：すべてのツールではなく、特定のツールをターゲットにする

• 徹底的にテストする：フックマネージャーを使用して動作を確認する

トランスポートの型¶

Cortexコードは3つのMCPトランスポート型をサポートしています。

OAuthを使用して、HTTPMCPサーバーへの認証ができます。OAuth用に構成されたサーバーに初めて接続するとき。Cortex Code CLIは、ユーザーが認証するブラウザウィンドウを開きます。結果のトークンは ~/.snowflake/cortex/mcp_oauth/ に保存され、必要に応じて自動的にリフレッシュされます。以下はサンプル OAuth 構成です。

{
   "oauth": {
      "client_id": "pre-registered-client-id",
      "client_name": "My Client",
      "redirect_port": 8585,
      "scope": "openid mcp read write",
      "authorization_server_url": "https://auth.example.com"
   }
}

MCPサーバーの管理¶

インタラクティブなCortex Code CLIセッションに /mcp コマンドを発行し、インタラクティブMCPステータスビューアーを開きます。cortex mcp コマンドを使用して、コマンドラインからMCPサーバー構成を管理します。

cortex mcp add <name> <command> [args...]

--transport, -t    Transport type (stdio, http, sse)
--type             Alias for --transport
--env, -e          Environment variable (KEY=value)
--header, -H       HTTP header
--timeout          Connection timeout in ms

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

MCP 設定¶

MCPサーバーの構成は、キー mcpServers 下の ~/.snowflake/cortex/mcp.json に保存されています。次の例は、単一のMCPサーバーを含む構成ファイルの構造を示しています。

{
   "mcpServers": {
      "server-name": {
         "type": "stdio",
         "command": "command-to-run",
         "args": ["arg1", "arg2"]
      }
   }
}

{
"mcpServers": {
   "my-server": {
      "type": "http",
      "url": "https://api.example.com",
      "headers": {
      "Authorization": "Bearer ${MY_API_TOKEN}"
      }
   }
}

export GITHUB_TOKEN="your_token_here"

MCPツールの使用¶

構成が完了すると、Cortex Code CLIセッションでMCPツールが自動的に利用可能になります。自然言語コマンドを使ってそれらを呼び出します。

Show me recent GitHub pull requests
Create a Jira ticket for this bug
Query the PostgreSQL database for user activity

初回使用時に権限がリクエストされます。~/.snowflake/cortex/permissions.json のデフォルトを構成します。

{
  "allow": ["mcp__github__read_file", "mcp__github__list_repos"],
  "deny": ["mcp__github__delete_repo"]
}

サンプルMCP構成¶

次の例は、一般的なユースケース用のMCPサーバー構成です。

{
  "mcpServers": {
    "git": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/path/to/repo"]
    }
  }
}

{
  "mcpServers": {
    "my-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "oauth": {
        "client_id": "my-client-id",
        "redirect_port": 8585,
        "scope": "openid mcp"
      }
    }
  }
}

{
  "mcpServers": {
    "realtime": {
      "type": "sse",
      "url": "https://realtime.example.com/events",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}",
        "X-Custom-Header": "value"
      },
      "timeout": 30000
    }
  }
}

{
  "mcpServers": {
    "sourcegraph": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@sourcegraph/mcp-server"],
      "env": {
        "SRC_ACCESS_TOKEN": "${SOURCEGRAPH_TOKEN}",
        "SRC_ENDPOINT": "https://sourcegraph.company.com"
      }
    }
  }
}

MCPのトラブルシューティング¶

サーバーが接続しない

• セッション中に /mcp をチェックしてリストされていることを確認する

• cortex mcp start <サーバー> を使用して接続をテストする

• 環境変数で認証情報が正しく設定されていることを確認する

• cat ~/.snowflake/cortex/logs/mcp.log を使用してヒントを得るためにログをレビューする

ツールが表示されない

• cortex mcp list を実行して構成を確認する

• ツール名が有効であることを確認する（英数字、アンダースコア、ハイフンのみを含む）

• ツール名が64文字より短いことを確認する

OAuthの問題

• キャッシュされたトークンをクリアする： rm ~/.snowflake/cortex/mcp_oauth/{server}*

• 再接続して新しいOAuthフローをトリガーする

• リダイレクトポートが利用可能であることを確認する（デフォルト8585）

環境変数が展開されない

• $VAR ではなく ${VAR} 構文（中括弧付き）を使用する

• シェルで 変数が設定されていることを確認する（ echo $VAR ）

• 変数名の誤入力をチェックする

MCPのベストプラクティス¶

• 説明的なサーバー名を使用することによってツールの名前空間をクリアにする

• 適切なタイムアウトを設定する：ツールリストのデフォルトは10分

• 安全な認証情報：ハードコードされたシークレットではなく、環境変数を使用する

• 接続をテスト：サーバーに依存する前に cortex mcp start を使用する