Extensibilidade da Cortex Code CLI¶

O que são habilidades?¶

As habilidades são arquivos Markdown com:

• Instruções específicas do domínio e práticas recomendadas

• Quando usar a habilidade

• Fluxos de trabalho de exemplo

• Configurações opcionais da ferramenta

Quando você invoca uma habilidade, as instruções dela são injetadas no contexto da conversa.

Usando as habilidades¶

Execute /skill list para listar as habilidades disponíveis e invoque-as pelo nome para carregá-las na conversa.

Locais das habilidades¶

As habilidades são carregadas de vários locais, listados abaixo em ordem de prioridade da mais alta para a mais baixa:

Criando habilidades personalizadas¶

As habilidades são diretórios que contêm um arquivo SKILL.md com as instruções de cada habilidade, além de exemplos e modelos opcionais. Você pode criar habilidades em um dos seguintes locais:

Para começar a criar uma habilidade personalizada:

1. Crie o diretório de habilidades. Este exemplo cria um diretório de habilidades chamado «my-skill» no local do projeto:

   mkdir -p .cortex/skills/my-skill
   

   Copy

2. Crie o SKILL.md nesse diretório e adicione as instruções da habilidade. Este exemplo mostra a estrutura básica:

   ---
   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. Verifique se sua habilidade aparece na listagem usando o comando $$:

   > $$
   

   Copy

   Se estiver listada, ela foi carregada corretamente e está disponível para uso.

4. Use sua habilidades em uma conversa:

   > $my-skill Test it out
   

   Copy

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

Gerenciando habilidades¶

Compondo habilidades¶

As habilidades personalizadas podem fazer referência a outras habilidades ou combinar habilidades com o contexto do arquivo:

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

Habilidades remotas¶

É possível adicionar habilidades remotas de repositórios Git. Um repositório pode conter qualquer número de habilidades. O layout das habilidades remotas deve corresponder à estrutura da habilidade local.

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

As habilidades remotas são armazenadas em cache localmente. Para atualizá-las, use /skill sync.

Referência de comandos de habilidade¶

Comandos CLI:

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

Comandos com barra:

/skill list
/skill add <path>

Solução de problemas de habilidades¶

A habilidade não é ativada

• Use uma linguagem específica relacionada ao propósito da habilidade

• Mencione a habilidade explicitamente: «use a otimização de exibição semântica»

• Verifique a disponibilidade: /skill list

Comportamento inesperado

• Forneça mais contexto sobre seu objetivo

• Tente uma solicitação mais específica

• Envie feedback: /feedback

Tipos de subagentes internos¶

Executando subagentes¶

O Cortex Code delega automaticamente a subagentes quando apropriado. Por exemplo, esta consulta delega a um agente Explore:

> Find all files that import the authentication module

Você também pode solicitar explicitamente tipos de subagentes específicos por nome:

> 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

Você também pode solicitar que vários subagentes sejam executados em paralelo para lidar com diferentes aspectos de uma tarefa:

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

Os agentes podem ser executados em segundo plano enquanto você continua seu trabalho:

> Run a background agent to refactor all the test files

O agente é iniciado imediatamente e retorna um ID de agente para rastreamento. Quando o agente for concluído, você poderá recuperar a saída usando esse ID:

> Get the output from agent abc1234

Para monitorar o status de todos os subagentes em execução, use o comando /agents (ou pressione Ctrl-B) para abrir o visualizador de processos em segundo plano. É possível parar um agente em execução usando o ID dele ou com a interface /agents:

> kill agent abc1234

Os agentes encerrados param de ser executados, mas mantêm o contexto indefinidamente. Você pode retomar um agente encerrado usando o ID dele:

> Resume agent abc1234 and continue from where it left off

Tipos de agente¶

Autônomo

Um agente autônomo é executado sem interação do usuário. O agente:

• é concluído forma independente;

• nunca é bloqueado para perguntas;

• é adequado para tarefas bem definidas.

Não autônomo

Um agente não autônomo pode pausar a execução para fazer perguntas ao usuário. O agente:

• pode fazer perguntas de esclarecimento;

• pode solicitar permissões interativamente;

• é adequado para tarefas que precisam de orientação.

Personalizado

Os agentes personalizados são subagentes definidos pelo usuário com prompts e configurações especializados. Você cria agentes adaptados a domínios ou fluxos de trabalho específicos em arquivos Markdown, semelhantes às habilidades personalizadas.

Criando subagentes personalizados¶

Os subagentes personalizados são definidos em arquivos Markdown com frontmatter do YAML. O frontmatter especifica o nome, a descrição, o acesso a ferramentas e o modelo do agente. O corpo contém o prompt do sistema que orienta o comportamento do agente.

Você pode armazenar arquivos Markdown de agentes personalizados em um destes três locais:

Veja a seguir o formato de uma definição de agente:

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

Isolamento da árvore de trabalho¶

Os agentes podem ser executados em árvores de trabalho ou ramificações git isoladas. Quando você solicita o isolamento da árvore de trabalho, a Cortex Code CLI cria uma árvore de trabalho git separada na qual o agente vai operar. Isso permite que vários agentes sejam executados em paralelo sem alterações conflitantes e é fácil de limpar posteriormente. Árvores de trabalho isoladas são particularmente úteis para exploração e experimentação. A ramificação git criada pelo agente é chamada agent/<agentId>.

Para usar o isolamento da árvore de trabalho, basta incluí-lo no prompt:

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

Padrão swarm (enxame)¶

Você pode iniciar um «enxame» de agentes para processar diferentes aspectos de uma tarefa complexa em paralelo. Cada agente opera de forma independente, e os resultados são agregados quando todos os agentes são concluídos. Todos os tipos de agentes podem participar de um swarm.

Veja a seguir alguns casos de uso de swarms:

• Análise de código: vários agentes analisam diferentes aspectos

• Refatoração: agentes paralelos processam arquivos diferentes

• Teste: os agentes executam diferentes conjuntos de testes

• Documentação: os agentes documentam diferentes componentes

Para criar um swarm, basta descrever os diferentes agentes que deseja iniciar:

> 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

Práticas recomendadas para subagentes¶

Use os subagentes para:

• Tarefas complexas: divisão em subtarefas para execução paralela

• Exploração: uso do agente Explore para pesquisas de base de código

• Planejamento: uso do agente Plan antes das principais alterações

• Trabalho em segundo plano: tarefas de longa duração que não precisam de atenção

Os subagentes podem não ser ideais para:

• Consultas simples: as ferramentas diretas são mais rápidas

• Edições de arquivo único: o agente principal é mais eficiente

• Trabalho interativo: quando você precisa de feedback imediato

Geralmente, os prompts detalhados são mais eficientes:

Visualizando os subagentes ativos¶

Comando /agents

Emita o comando /agents em uma sessão do Cortex Code para abrir o visualizador de agente interativo. Essa interface mostra todos os agentes em execução, os respectivos tipos, status e prévias de saída.

Visualizador de processo em segundo plano

Em uma sessão da Cortex Code CLI, pressione Ctrl-B para visualizar:

• Todos os processos em segundo plano

• Sessões do agente

• Processos Bash

Limites do agente¶

Os seguintes limites se aplicam a subagentes na Cortex Code CLI:

• Máximo de 50 agentes simultâneos em segundo plano

• Os agentes herdam as permissões da sessão

• Os agentes em segundo plano não podem gerar outros agentes em segundo plano

Eventos de gancho¶

Os seguintes eventos podem acionar ganchos:

Configurando ganchos¶

Os ganchos são definidos em arquivos de configurações, que podem residir em qualquer diretório de configuração (listados abaixo em ordem de prioridade da mais alta para a mais baixa):

Os ganchos são definidos em formato JSON, especificando o evento, a correspondência de ferramenta e as ações do gancho. Veja abaixo um exemplo simples de gancho para pré-uso da ferramenta:

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

Dois tipos de gancho são compatíveis: de comando e de prompt.

• Os ganchos de comando executam comandos ou scripts do shell.

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

  Copy

• Os ganchos de prompt são avaliados como prompts de linguagem natural para um modelo de linguagem.

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

  Copy

Para executar o gancho somente em ferramentas específicas, insira os nomes das ferramentas ou os padrões no campo matcher. Por exemplo, para corresponder a todas as ferramentas SQL, use "matcher": "SQL*". Você pode usar expressões regulares para corresponder a várias ferramentas.

Escrevendo scripts de gancho¶

Os scripts de gancho aceitam uma entrada JSON via entrada padrão e retornam uma saída JSON via saída padrão. A saída contém um campo indicando se a operação é permitida ou negada. Opcionalmente, o script de gancho pode retornar uma versão modificada da entrada da ferramenta.

Entrada de amostra:

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

Exemplo de saída:

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

O código de retorno indica se a operação deve ser bloqueada:

• 0: não bloquear

• 2: bloquear

Essas informações também podem ser retornadas como parte da saída JSON, como mostrado abaixo.

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

As seguintes variáveis de ambiente estão disponíveis nos scripts de gancho:

Exemplos de ganchos¶

Os exemplos a seguir ilustram a saída possível para casos de uso de gancho comuns.

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

Práticas recomendadas para ganchos¶

• Mantenha os ganchos rápidos: o tempo limite padrão é de 60 segundos

• Trate os erros de forma adequada: saída de retorno 0 em caso de dúvida

• Registre em log para depuração: grave em arquivos para solução de problemas

• Use correspondências: foque em ferramentas específicas, não todas

• Faça um teste detalhado: use o gerenciador de ganchos para verificar o comportamento

Tipos de transporte¶

O Cortex Code oferece suporte a três tipos de transporte MCP:

Você pode usar o OAuth para autenticação em servidores MCP por HTTP. A primeira vez que você se conecta a um servidor configurado para OAuth, a Cortex Code CLI abre uma janela do navegador, na qual o usuário se autentica. O token resultante é armazenado em ~/.snowflake/cortex/mcp_oauth/ e atualizado automaticamente conforme necessário. Veja a seguir uma configuração do OAuth de amostra:

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

Gerenciando servidores MCP¶

Você pode emitir o comando /mcp em uma sessão interativa da Cortex Code CLI para abrir um visualizador de status de MCP interativo. Use o comando cortex mcp para gerenciar as configurações do servidor MCP pela linha de comando.

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}

Configuração do MCP¶

A configuração do servidor MCP é armazenada em ~/.snowflake/cortex/mcp.json sob a chave mcpServers. O exemplo a seguir mostra a estrutura de um arquivo de configuração com um servidor MCP único:

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

Usando as ferramentas MCP¶

Após a configuração, as ferramentas MCP estarão disponíveis automaticamente nas sessões da Cortex Code CLI. Você as invoca por meio de comandos de linguagem natural:

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

As permissões são solicitadas no primeiro uso. Configure os padrões em ~/.snowflake/cortex/permissions.json:

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

Configurações do MCP de amostra¶

Os exemplos a seguir ilustram as configurações do servidorMCP para casos de uso comuns.

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

Solução de problemas do MCP¶

Servidor não conecta

• Verifique o /mcp durante uma sessão para garantir que ele esteja listado

• Use cortex mcp start <servidor> para testar a conectividade

• Garanta que as credenciais estejam definidas corretamente nas variáveis de ambiente

• cat ~/.snowflake/cortex/logs/mcp.log para revisar o log em busca de pistas

Ferramentas que não aparecem

• Execute cortex mcp list para verificar a configuração

• Certifique-se de que os nomes das ferramentas sejam válidos (contêm apenas caracteres alfanuméricos, sublinhados e hifens)

• Verifique se os nomes das ferramentas têm menos de 64 caracteres

Problemas com o OAuth

• Limpe os tokens armazenados em cache: rm ~/.snowflake/cortex/mcp_oauth/{server}*

• Reconecte para acionar o novo fluxo do OAuth

• Verifique se a porta de redirecionamento está disponível (padrão 8585)

Variáveis de ambiente não são expandidas

• Use a sintaxe ${VAR} (com chaves) em vez de $VAR

• Certifique-se de que a variável esteja definida no shell (echo $VAR)

• Verifique se há erros de digitação nos nomes das variáveis

Práticas recomendadas para MCP¶

• Use nomes de servidor descritivos: torna claro o uso de namespace das ferramentas

• Defina tempos limite apropriados: o padrão é 10 minutos para listagem de ferramentas

• Proteja as credenciais: use variáveis de ambiente em vez de segredos codificados

• Teste as conexões: use cortex mcp start antes de confiar em um servidor