Cortex Code CLI 可扩展性¶

什么是 Skill？¶

Skill 是包含以下内容的 Markdown 文件：

• 特定领域的指令和最佳实践

• 何时利用 Skill

• 示例工作流程

• 可选工具配置

当您调用某个 Skill 时，其指令会被注入到对话上下文中。

使用 Skill¶

运行 /skill list 列出可用的 Skill，并通过名称调用它们，将对应 Skill 加载到对话中。

Skill 位置¶

Skill 从多个位置加载，下面按优先级从高到低列出：

创建自定义 Skill¶

Skill 是包含 SKILL.md 文件的目录，该文件包含 Skill 指令，并可包含可选的示例和模板。您可以在以下位置之一创建 Skill：

要开始构建自定义 Skill，请执行以下操作：

1. 创建 Skill 目录。此示例在项目位置创建一个名为“my-skill”的 Skill 目录：

   mkdir -p .cortex/skills/my-skill
   

   Copy

2. 在该目录中创建 SKILL.md 文件，并添加 Skill 指令。此示例展示了基本结构：

   ---
   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]
   

   Copy

3. 使用 $$ 命令验证您的 Skill 是否出现在列表中：

   > $$
   

   Copy

   如果您的 Skill 出现在列表中，则说明其已正确加载并可供使用。

4. 在对话中使用您的 Skill：

   > $my-skill Test it out
   

   Copy

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

管理 Skill¶

组合 Skill¶

自定义 Skill 可以引用其他 Skill，或将 Skill 与文件上下文相结合：

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

远程 Skill¶

您可以从 Git 存储库添加远程 Skill。一个存储库可以包含任意数量的 Skill。远程 Skill 的布局应与本地 Skill 结构相匹配。

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

远程 Skill 在本地缓存。要更新，请使用 /skill sync。

Skill 命令参考¶

CLI 命令：

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

斜杠命令：

/skill list
/skill add <path>

Skill 故障排除¶

Skill 未激活

• 使用与 Skill 目的相关的特定语言

• 明确提及 Skill：“Use semantic-view-optimization”

• 检查可用性：/skill list

意外行为

• 提供有关目标的更多背景信息

• 尝试更具体的请求

• 提交反馈：/feedback

内置 Subagent 类型¶

运行 Subagent¶

Cortex Code 会在适当情况下自动委派给 Subagent。例如，此查询委托给 Explore 代理：

> Find all files that import the authentication module

您还可以按名称显式请求特定的 Subagent 类型：

> 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

您还可以请求多个 Subagent 并行运行，以处理任务的不同方面：

> 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

要监控所有正在运行的 Subagent 状态，请使用 /agents 命令（或按 Ctrl-B）打开后台进程查看器。您可以使用其 ID 停止正在运行的代理，或通过 /agents 界面操作：

> kill agent abc1234

被终止的代理会停止运行，但其上下文会被无限期保留。您可以使用其 ID 恢复已终止的代理：

> Resume agent abc1234 and continue from where it left off

代理类型¶

自治

自治代理无需用户交互即可运行。代理：

• 独立完成

• 不会阻塞提问

• 适合明确定义的任务

非自治

非自治代理可以暂停执行以向用户提问。代理：

• 可能会提出澄清性问题

• 可以交互式请求权限

• 适合需要指导的任务

自定义

自定义代理是用户定义的 Subagent，具有专门的提示和配置。您可以在 Markdown 文件中创建针对特定领域或工作流程的代理，类似于自定义 Skill。

创建自定义 Subagent¶

自定义子代理在带有 YAML 前置信息的 Markdown 文件中定义。前置信息指定了代理的名称、描述、工具访问权限和模型。正文包含指导代理行为的系统提示。

您可以将自定义代理 Markdown 文件存储在以下三个位置之一：

代理定义的格式如下所示：

---
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

Subagent 最佳实践¶

将 Subagent 用于以下用途：

• 复杂任务：分解为可并行执行的子任务

• 探索：使用 Explore 代理进行代码库搜索

• 规划：在重大变更之前使用 Plan 代理

• 后台工作：不需要关注的长时间运行的任务

Subagent 可能不适合以下情况：

• 简单查询：直接使用工具更快

• 单文件编辑：主代理更高效

• 交互式工作：当您需要即时反馈时

详细提示通常更有效：

查看活动 Subagent¶

/agents 命令

在 Cortex Code 会话中使用 /agents 命令打开交互式代理查看器。该界面显示所有正在运行的代理及其类型、状态和输出预览。

后台进程查看器

在 Cortex Code CLI 会话中，按 Ctrl-B 可查看：

• 所有后台进程

• 代理会话

• Bash 进程

代理限制¶

以下限制适用于 Cortex Code CLI 中的 Subagent：

• 最多 50 个并发后台代理

• 代理继承会话权限

• 后台代理无法生成其他后台代理

Hook 事件¶

以下事件可以触发 Hook：

配置 Hook¶

Hook 在设置文件中配置，这些文件可以位于任意配置目录（按优先级从高到低列出）：

Hook 以 JSON 格式定义，指定事件、工具匹配器和 Hook 操作。下面显示了一个工具使用前 Hook 的简单示例：

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

支持两种 Hook 类型：命令 Hook 和提示 Hook。

• 命令 Hook 运行 Shell 命令或脚本。

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

  Copy

• 提示 Hook 被评估为语言模型的自然语言提示。

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

  Copy

要仅在特定工具上执行 Hook，请将工具名称或模式放在 matcher 字段中。例如，要匹配所有 SQL 工具，请使用 "matcher": "SQL*"。您可以使用正则表达式匹配多个工具。

编写 Hook 脚本¶

Hook 脚本通过标准输入接收 JSON 输入，并通过标准输出返回 JSON 输出。输出中包含一个字段，用于指示操作是被允许还是被拒绝。（可选）Hook 脚本可以返回工具输入的修改版本。

示例输入：

{
  "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"
}

Hook 脚本中提供以下环境变量：

Hook 示例¶

以下示例展示了常见 Hook 用例的可能输出。

{
  "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"
  }
}

Hook 最佳实践¶

• 保持 Hook 快速：超时默认为 60 秒

• 优雅地处理错误：如果不确定，则返回 exit 0

• 用于调试的日志：写入文件以进行故障排除

• 使用匹配器：针对特定工具，而非全部工具

• 彻底测试：使用 Hook 管理器验证行为

传输类型¶

Cortex Code 支持三种 MCP 传输类型：

您可以使用 OAuth 对 HTTP MCP 服务器进行身份验证。首次连接到配置为 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 服务器配置存储在 ~/.snowflake/cortex/mcp.json 中的键 mcpServers 下。以下示例显示了包含单个 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 工具¶

配置完成后，MCP 工具会在 Cortex Code CLI 会话中自动可用。您可通过自然语言命令调用它们：

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

• 确保在 Shell 中设置了变量 (echo $VAR)

• 检查变量名称中的拼写错误

MCP 最佳实践¶

• 使用描述性服务器名称：使工具命名空间清晰

• 设置适当的超时：工具列表默认超时为 10 分钟

• 安全凭据：使用环境变量，而非硬编码密钥

• 测试连接：在依赖服务器之前使用 cortex mcp start