Erweiterbarkeit der Cortex Code CLI¶

Was sind Skills?¶

Skills sind Markdown-Dateien, die Folgendes enthalten:

• Domänenspezifische Anweisungen und Best Practices

• Wann das Skill verwendet werden soll

• Beispiel-Workflows

• Optionale Toolkonfigurationen

Wenn Sie ein Skill aufrufen, werden ihre Anweisungen in den Konversationskontext eingefügt.

Verwenden von Skills¶

Führen Sie /skill list aus, um die verfügbaren Skills aufzulisten, und rufen Sie diese nach Namen auf, um das Skill in die Konversation zu laden.

Skills-Speicherorte¶

Skills werden aus mehreren Speicherorten geladen, die nachfolgend von der höchsten zur niedrigsten Priorität aufgeführt sind:

Erstellen von kundenspezifischen Skills¶

Skills sind Verzeichnisse, die eine SKILL.md-Datei mit Anleitungen für Skills sowie optionalen Beispiele und Vorlagen enthalten. Sie können Skills an einem der folgenden Orte erstellen:

So beginnen Sie mit dem Erstellen eines kundenspezifischen Skills:

1. Erstellen Sie das Skill-Verzeichnis. In diesem Beispiel wird am Projektspeicherort ein Skill-Verzeichnis namens „my-skill“ erstellt:

   mkdir -p .cortex/skills/my-skill
   

   Copy

2. Erstellen Sie SKILL.md in diesem Verzeichnis und fügen Sie Anleitungen für Skills hinzu. Dieses Beispiel zeigt die Grundstruktur:

   ---
   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. Überprüfen Sie anhand des Befehls $$, ob das Skill in der Liste angezeigt wird:

   > $$
   

   Copy

   Wenn Ihre Skills aufgeführt sind, wurden sie korrekt geladen und können verwendet werden.

4. Ihre Skills in einer Konversation nutzen:

   > $my-skill Test it out
   

   Copy

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

Verwalten von Skills¶

Entwerfen von Skills¶

Kundenspezifische Skills können auf andere Skills verweisen oder Skills mit dem Dateikontext kombinieren:

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

Remote-Skills¶

Sie können Remote-Skills aus Git-Repositorys hinzufügen. Ein Repository kann eine beliebige Anzahl von Skills enthalten. Das Layout der Remote-Skills sollte mit der lokalen Skills-Struktur übereinstimmen.

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

Remote-Skills werden lokal zwischengespeichert. Verwenden Sie zum Aktualisieren /skill sync.

Skill-Befehlsreferenz¶

CLI-Befehle:

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

Schrägstrich-Befehle:

/skill list
/skill add <path>

Problembehandlung für Skills¶

Skill wird nicht aktiviert

• Bestimmte Sprache verwenden, die sich auf den Zweck des Skills bezieht

• Erwähnen Sie das Skill explizit: „Use semantic-view-optimization“

• Verfügbarkeit prüfen: /skill list

Unerwartetes Verhalten

• Geben Sie mehr Kontext zu Ihrem Ziel an

• Versuchen Sie es mit einer genaueren Anfrage

• Feedback übermitteln: /feedback

Integrierten Type von Subagenten¶

Ausführen von Subagenten¶

Cortex Code delegiert bei Bedarf automatisch an Subagenten. Die folgende Abfrage wird zum Beispiel an einen Explore-Agenten delegiert:

> Find all files that import the authentication module

Sie können bestimmte Typen von Subagenten auch explizit über den Namen anfordern:

> 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

Sie können auch anfordern, dass mehrere Subagenten parallel ausgeführt werden, um verschiedene Aspekte einer Aufgabe anzugehen:

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

Agenten können im Hintergrund ausgeführt werden, während Sie weiterarbeiten:

> Run a background agent to refactor all the test files

Der Agent startet sofort und gibt eine Agenten-ID für die Verfolgbarkeit zurück. Wenn der Agent fertig ist, können Sie seine Ausgabe anhand seiner ID abrufen:

> Get the output from agent abc1234

Um den Status aller laufenden Subagenten zu überwachen, verwenden Sie den /agents-Befehl (oder drücken Sie Strg+B), um den Hintergrund-Prozessbetrachter zu öffnen. Sie können einen laufenden Agenten mit seiner ID oder über die /agents-Schnittstelle anhalten:

> kill agent abc1234

Beendete Agenten werden nicht mehr ausgeführt, behalten aber ihren Kontext auf unbestimmte Zeit bei. Sie können einen beendeten Agenten anhand seiner ID fortsetzen:

> Resume agent abc1234 and continue from where it left off

Typen von Agenten¶

Autonom

Ein autonomer Agent wird ohne Benutzerinteraktion ausgeführt. Der Agent:

• schließt seine Ausführung eigenständig ab

• blockiert niemals für Fragen

• ist für genau definierte Aufgaben geeignet

Nicht autonom

Ein nicht autonomer Agent kann die Ausführung pausieren, um dem Benutzenden Fragen zu stellen. Der Agent:

• kann klärende Fragen stellen

• kann Berechtigungen interaktiv anfordern

• ist für Aufgaben geeignet, die eine Anleitung benötigen

Kundenspezifisch

Kundenspezifische Agenten sind benutzerdefinierte Subagenten mit speziellen Prompts und Konfigurationen. Sie erstellen Agenten, die auf bestimmte Domänen oder Workflows in Markdown-Dateien zugeschnitten sind, ähnlich wie bei kundenspezifischen Skills.

Erstellen von kundenspezifischen Subagenten¶

Kundenspezifische Subagenten werden in Markdown-Dateien mit YAML-Frontmatter definiert. Das Frontmatter gibt den Namen des Agenten, die Beschreibung, den Zugriff auf die Tools und das Modell an. Der Haupttext enthält den System-Prompt, der das Verhalten des Agenten steuert.

Sie können Markdown-Dateien für kundenspezifische Agenten an einem von drei Orten speichern:

Das Format einer Agentendefinition ist unten dargestellt:

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

Arbeitsstrukturisolierung¶

Agenten können in isolierten Git-Arbeitsstrukturen oder Branches ausgeführt werden. Wenn Sie die Isolation der Arbeitsstruktur anfordern, erstellt Cortex Code CLI eine separate Git-Arbeitsstruktur, in der der Agent operieren kann. So können mehrere Agenten parallel ausgeführt werden, ohne dass Änderungen kollidieren, und die Änderungen sind anschließend leicht zu bereinigen. Isolierte Arbeitsstrukturen sind besonders nützlich für Erkundungen und Experimente. Der vom Agenten erstellte Git-Zweig heißt agent/<Agenten-ID>.

Um die Arbeitsstrukturisolierung zu verwenden, fügen Sie sie einfach in Ihren Prompt ein:

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

Schwarmmuster¶

Sie können einen Schwarm von Agenten starten, um verschiedene Aspekte einer komplexen Aufgabe parallel anzugehen. Jeder Agent arbeitet eigenständig, und die Ergebnisse werden zusammengefasst, sobald alle Agenten beendet sind. Alle Arten von Agenten können an einem Schwarm beteiligt sein.

Schwarm-Anwendungsfälle:

• Code-Analyse: Mehrere Agenten analysieren unterschiedliche Aspekte

• Umstrukturierung: Parallele Agenten verarbeiten verschiedene Dateien

• Testen: Agenten führen verschiedene Testsuiten aus

• Dokumentation: Agenten dokumentieren verschiedene Komponenten

Um einen Schwarm zu erstellen, beschreiben Sie einfach die verschiedenen Agenten, die Sie starten möchten:

> 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

Best Practices für Subagenten¶

Verwenden Sie Subagenten für:

• Komplexe Aufgaben: Aufteilen in Unteraufgaben zur parallelen Ausführung

• Erkundung: Verwenden Sie den Explore-Agenten zum Suchen in der Codebasis

• Planung: Verwenden Sie den Plan-Agenten vor größeren Änderungen

• Hintergrundarbeit: Zeitintensive Aufgaben, die keine Aufmerksamkeit erfordern

Subagenten sind möglicherweise nicht ideal für:

• Einfache Abfragen: Direkte Tools sind schneller

• Änderungen an einzelnen Dateien: Der Hauptagent ist effizienter

• Interaktives Arbeiten: Wenn Sie sofortiges Feedback benötigen

Detaillierte Prompts sind im Allgemeinen effektiver:

Anzeigen von aktiven Subagenten¶

Befehl /agents

Geben Sie den Befehl /agents in einer Cortex Code-Sitzung aus, um den interaktiven Agentenbetrachter zu öffnen. In dieser Oberfläche werden alle aktiven Agenten, ihre Typen, die Status und die Vorschau der Ausgabe angezeigt.

Hintergrund-Prozessbetrachter

Drücken Sie in einer Cortex Code CLI-Sitzung die Tastenkombination Strg+B, um Folgendes anzuzeigen:

• Alle Hintergrundprozesse

• Agentensitzungen

• Bash-Prozesse

Einschränkungen bei Agenten¶

Die folgenden Einschränkungen gelten für Subagenten in Cortex Code CLI:

• Maximal 50 gleichzeitige Hintergrundagenten

• Agenten erben Sitzungsberechtigungen

• Hintergrundagenten können keine anderen Hintergrundagenten erzeugen

Hook-Ereignisse¶

Die folgenden Ereignisse können Hooks auslösen:

Konfigurieren von -Hooks¶

Hooks werden in Einstellungsdateien konfiguriert, die sich in einem beliebigen Konfigurationsverzeichnis befinden können (nachfolgend von der höchsten zur niedrigsten Priorität aufgeführt):

Hooks werden im JSON-Format unter Angabe des Ereignisses, des Tool-Matchers und der Hook-Aktionen definiert. Ein einfaches Beispiel für einen Hook vor Tool-Verwendung finden Sie unten:

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

Es werden zwei Hook-Typen unterstützt: Befehls-Hooks und Prompt-Hooks.

• Befehls-Hooks führen Shell-Befehle oder Skripte aus.

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

  Copy

• Prompt-Hooks werden als Prompts in natürlicher Sprache für ein Sprachmodell ausgewertet.

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

  Copy

Um den Hook nur für bestimmte Tools auszuführen, platzieren Sie die Tool-Namen oder -Muster im Feld matcher. Verwenden Sie zum Beispiel zum Abgleichen aller SQL-Tools "matcher": "SQL*". Sie können reguläre Ausdrücke verwenden, um mehreren Tools abzugleichen.

Schreiben von Hook-Skripten¶

Hook-Skripte akzeptieren JSON-Eingaben mittels der Standardeingabe und geben JSON-Ausgaben über die Standardausgabe zurück. Die Ausgabe enthält ein Feld, das angibt, ob der Vorgang zulässig oder unzulässig ist. Optional kann das Hook-Skript eine geänderte Version der Tool-Eingabe zurückgeben.

Beispieleingabe:

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

Beispielausgabe:

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

Der Rückgabecode gibt an, ob der Vorgang blockiert werden soll:

• 0: Nicht blockieren

• 2: Blockieren

Diese Informationen können auch als Teil der JSON-Ausgabe zurückgegeben werden, wie unten gezeigt.

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

Die folgenden Umgebungsvariablen sind in Hook-Skripten verfügbar:

Hook-Beispiele¶

Die folgenden Beispiele veranschaulichen die mögliche Ausgabe für häufige Hook-Anwendungsfälle.

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

Best Practices für Hooks¶

• Hooks sollten schnell sein: Das Timeout beträgt standardmäßig 60 Sekunden

• Fehler sollten optimal gehandhabt werden: „exit 0“ zurückgeben, wenn nicht sicher

• Protokolle für Debugging: Zur Problembehandlung in Dateien schreiben

• Matcher verwenden: Auf bestimmte Tools abzielen, nicht auf alle

• Gründlich testen: Hook-Manager verwenden, um das Verhalten zu überprüfen

Transporttypen¶

Cortex Code unterstützt drei MCP-Transporttypen:

Sie können OAuth für die Authentifizierung bei HTTP MCP-Servern verwenden. Wenn Sie zum ersten Mal eine Verbindung zu einem -Server herstellen, der für OAuth konfiguriert ist, öffnet Cortex Code CLI ein Browserfenster, in dem sich der Benutzer authentifiziert. Das resultierende Token wird in ~/.snowflake/cortex/mcp_oauth/ gespeichert und bei Bedarf automatisch aktualisiert. Nachfolgenden sehen Sie ein Beispiel für eine OAuth-Konfiguration:

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

Verwalten von MCP-Servern¶

Sie können den Befehl /mcp in einer interaktiven Cortex Code CLI-Sitzung ausgeben, um einen interaktiven MCP-Statusbetrachter zu öffnen. Verwenden Sie den Befehl cortex mcp, um MCP-Serverkonfigurationen über die Befehlszeile zu verwalten.

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

Die MCP-Serverkonfiguration wird in ~/.snowflake/cortex/mcp.json unter dem Schlüssel mcpServers gespeichert. Das folgende Beispiel zeigt die Struktur einer Konfigurationsdatei mit einem einzelnen MCP-Server:

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

Verwenden von MCP-Tools¶

Sobald sie konfiguriert sind, stehen MCP-Tools automatisch in Cortex Code CLI-Sitzungen zur Verfügung. Sie rufen sie anhand von Befehlen in natürlicher Sprache auf:

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

Bei der erstmaligen Verwendung werden Berechtigungen angefordert. Konfigurieren von Standards in ~/.snowflake/cortex/permissions.json:

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

MCP-Beispielkonfigurationen¶

Die folgenden Beispiele veranschaulichen MCP-Serverkonfigurationen für gängige Anwendungsfälle.

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

Problembehandlung für MCP¶

Server stellt keine Verbindung her

• Überprüfen Sie /mcp während einer Sitzung, um sicherzustellen, dass es aufgeführt ist.

• Verwenden Sie cortex mcp start <-Server>, um die Konnektivität zu testen.

• Stellen Sie sicher, dass die Anmeldeinformationen in den Umgebungsvariablen korrekt festgelegt sind.

• Sehen Sie sich cat ~/.snowflake/cortex/logs/mcp.log auf Hinweise an.

Tools werden nicht angezeigt

• Führen Sie cortex mcp list aus, um die Konfiguration zu prüfen.

• Stellen Sie sicher, dass die Tool-Namen gültig sind (nur alphanumerische Zeichen, Unterstriche und Bindestriche enthalten).

• Prüfen Sie, ob die Tool-Namen kürzer als 64 Zeichen sind.

Probleme mit OAuth

• Zwischengespeicherte Token löschen: rm ~/.snowflake/cortex/mcp_oauth/{server}*

• Erneut verbinden, um neuen OAuth-Fluss auszulösen

• Prüfen Sie, ob der Umleitungport verfügbar ist (Standard 8585)

Umgebungsvariablen werden nicht erweitert

• ${VAR}-Syntax (mit Klammern) anstatt $VAR verwenden

• Sicherstellen, dass die Variable in der Shell festgelegt ist (echo $VAR)

• Prüfen Sie auf Rechtschreibfehler in Variablennamen

Best Practices für MCP¶

• Verwenden Sie beschreibende Servernamen: Machen Sie den Namespace des Tools deutlich

• Legen Sie die entsprechenden Timeouts fest: Die Standardeinstellung ist 10 Minuten für das Freigabeangebot des Tools

• Sichere Anmeldeinformationen: Verwenden Sie Umgebungsvariablen, keine hartcodierten Geheimnisse

• Verbindungen testen: Verwenden Sie cortex mcp start, bevor Sie sich auf einen Server verlassen.