Extensibilité de la CLI Cortex Code¶

Que sont les compétences ?¶

Les compétences sont des fichiers Markdown qui montrent :

• Des instructions et des bonnes pratiques spécifiques au domaine

• Quand utiliser une compétence

• Des exemples de workflows

• Des configurations d’outils facultatives

Lorsque vous invoquez une compétence, ses instructions sont injectées dans le contexte de la conversation.

Utilisation des compétences¶

Exécutez /skill list pour lister les compétences disponibles, et invoquez-les par leur nom pour charger la compétence dans la conversation.

Emplacements des compétences¶

Les compétences sont chargées à partir de plusieurs emplacements, listés ci-dessous de la priorité la plus élevée à la plus basse :

Création de compétences personnalisées¶

Les compétences sont des répertoires contenant un fichier SKILL.md avec des instructions sur les compétences, et des exemples et modèles facultatifs. Vous pouvez créer des compétences dans l’un des emplacements suivants :

Pour commencer à créer une compétence personnalisée, procédez comme suit :

1. Créez le répertoire de compétence. Cet exemple crée un répertoire de compétence nommé « my-skill » dans l’emplacement du projet :

   mkdir -p .cortex/skills/my-skill
   

   Copy

2. Créez SKILL.md dans ce répertoire et ajoutez des instructions de compétence. Cet exemple montre la structure de base :

   ---
   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. Vérifiez que votre compétence apparaît dans la liste à l’aide de la commande $$ :

   > $$
   

   Copy

   Si votre compétence est répertoriée, cela signifie qu’elle a été correctement chargée et qu’elle est disponible pour être utilisée.

4. Utilisez votre compétence dans une conversation :

   > $my-skill Test it out
   

   Copy

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

Gestion des compétences¶

Compétences compositionnelles¶

Les compétences personnalisées peuvent faire référence à d’autres compétences, ou combiner des compétences avec un contexte de fichier :

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

Compétences distantes¶

Vous pouvez ajouter des compétences distantes depuis les référentiels Git. Un référentiel peut contenir un nombre illimité de compétences. La disposition des compétences distantes doit correspondre à la structure des compétences locale.

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

Les compétences distantes sont mises en cache localement. Pour les mettre à jour, utilisez /skill sync.

Référence des commandes de compétences¶

Commandes CLI :

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

Commandes avec barre oblique :

/skill list
/skill add <path>

Résolution des problèmes liés aux compétences¶

Compétence non active

• Utilisez un langage spécifique lié à l’objectif de la compétence

• Mentionnez explicitement la compétence : « Utiliser l’optimisation de la vue sémantique »

• Vérifiez la disponibilité : /skill list

Comportement inattendu

• Donnez plus de contexte concernant votre objectif

• Essayez une requête plus spécifique

• Soumettez des commentaires : /feedback

Types de sous-agents intégrés¶

Sous-agents en cours d’exécution¶

Cortex Code délègue automatiquement aux sous-agents lorsque cela est possible. Par exemple, cette requête délègue à un agent Explore :

> Find all files that import the authentication module

Vous pouvez également demander explicitement des types de sous-agents spécifiques par leur nom :

> 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

Vous pouvez également demander à plusieurs sous-agents de s’exécuter en parallèle pour traiter différents aspects d’une tâche :

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

Les agents peuvent s’exécuter en arrière-plan pendant que vous continuez de travailler :

> Run a background agent to refactor all the test files

L’agent démarre immédiatement et renvoie un ID d’agent pour le suivi. Lorsque l’agent se termine, vous pouvez récupérer sa sortie à l’aide de son ID :

> Get the output from agent abc1234

Pour surveiller l’état de tous les sous-agents en cours d’exécution, utilisez la commande /agents (ou appuyez sur Ctrl-B) pour ouvrir la visionneuse des processus en arrière-plan. Vous pouvez arrêter un agent en cours d’exécution à l’aide de son ID, ou avec l’interface /agents :

> kill agent abc1234

Les agents arrêtés cessent de fonctionner, mais conservent leur contexte indéfiniment. Vous pouvez reprendre un agent arrêté à l’aide de son ID :

> Resume agent abc1234 and continue from where it left off

Types d’agents¶

Autonomes

Un agent autonome s’exécute sans interaction de l’utilisateur. L’agent :

• Se termine indépendamment

• Ne se bloque jamais pour poser des questions

• Est adapté pour les tâches bien définies

Non autonomes

Un agent non autonome peut suspendre l’exécution pour poser des questions à l’utilisateur. L’agent :

• Peut poser des questions de clarification

• Peut demander des autorisations de manière interactive

• Est adapté pour les tâches nécessitant des conseils

Personnalisés

Les agents personnalisés sont des sous-agents définis par l’utilisateur avec des configurations et des invites spécialisées. Vous créez des agents adaptés à des domaines ou à des workflows spécifiques dans des fichiers Markdown, de manière similaire à des compétences personnalisées.

Création de sous-agents personnalisés¶

Les sous-agents personnalisés sont définis dans des fichiers Markdown avec un en-tête YAML. L’en-tête spécifie le nom, la description, l’accès à l’outil et le modèle de l’agent. Le corps contient l’invite du système qui guide le comportement de l’agent.

Vous pouvez stocker des fichiers Markdown d’agents personnalisés à l’un des trois emplacements suivants :

Le format d’une définition d’agent est montré ci-dessous :

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

Isolement de l’arborescence de travail¶

Les agents peuvent être exécutés dans des arborescences de travail Git isolées ou des branches. Lorsque vous demandez l’isolement de l’arborescence de travail, la CLI Cortex Code crée une arborescence de travail Git distincte dans laquelle l’agent peut opérer. Cela permet à plusieurs agents de fonctionner en parallèle sans modifications conflictuelles et facilite le nettoyage ultérieur. Les arborescences de travail isolées sont particulièrement utiles pour l’exploration et l’expérimentation. La branche Git créée par l’agent est nommée agent/<agentId>.

Pour utiliser l’isolement de l’arborescence de travail, il suffit de l’inclure dans votre invite :

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

Modèle en essaim¶

Vous pouvez lancer un essaim d’agents pour traiter différents aspects d‘une tâche complexe en parallèle. Chaque agent fonctionne indépendamment, et les résultats sont agrégés lorsque tous les agents se terminent. Tous les types d’agents peuvent participer à un essaim.

Les cas d’utilisation des essaims comprennent :

• Analyse de code : plusieurs agents analysent différents aspects

• Refactorisation : des agents parallèles traitent des fichiers différents

• Test : des agents exécutent différentes suites de tests

• Documentation : des agents documentent différents composants

Pour créer un essaim, il suffit de décrire les différents agents que vous souhaitez lancer :

> 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

Bonnes pratiques en matière de sous-agents¶

Utilisez des sous-agents pour :

• Tâches complexes : Décomposez des tâches en sous-tâches pour une exécution parallèle

• Exploration : Utilisez l’agent Explore pour des recherches dans la base de code

• Planification : Utilisez l’agent Plan avant des modifications majeures

• Travail en arrière-plan : Tâches de longue durée qui ne nécessitent aucune attention particulière

Les sous-agents peuvent ne pas être idéaux pour :

• Requêtes simples : les outils directs sont plus rapides

• Modifications d’un seul fichier : l’agent principal est plus efficace

• Travail interactif : lorsque vous avez besoin de commentaires immédiats

Les invites détaillées sont généralement plus efficaces :

Affichage des sous-agents actifs¶

Commande /agents

Émettez la commande /agents dans une session Cortex Code pour ouvrir la visionneuse d’agents interactive. Cette interface affiche tous les agents en cours d’exécution, leurs types, leurs états et une prévisualisation des sorties.

Visionneuse des processus en arrière-plan

Dans une session CLI Cortex Code, appuyez sur Ctrl-B pour afficher :

• Tous les processus en arrière-plan

• Les sessions des agents

• Les processus Bash

Les limites des agents¶

Les limites suivantes s’appliquent aux sous-agents dans le CLI Cortex Code :

• Maximum de 50 agents en arrière-plan simultanés

• Les agents héritent des autorisations de session

• Les agents en arrière-plan ne peuvent pas générer d’autres agents en arrière-plan

Événements de hooks¶

Les événements suivants peuvent déclencher des hooks :

Configuration des hooks¶

Les hooks sont configurés dans des fichiers de paramètres, qui peuvent se trouver dans n’importe quel répertoire de configuration (répertoriés ci-dessous par ordre de priorité décroissante) :

Les hooks sont définis au format JSON, spécifiant l’événement, la correspondance de l’outil et les actions de hook. Un exemple simple d’un hook avant utilisation de l’outil est présenté ci-dessous :

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

Deux types de hooks sont pris en charge : les hooks de commande et les hooks d’invite.

• Les hooks de commande exécutent des commandes shell ou des scripts.

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

  Copy

• Les hooks d’invite sont évalués comme des invites en langage naturel pour un modèle de langage.

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

  Copy

Pour exécuter votre hook uniquement sur des outils spécifiques, placez les noms des outils ou les modèles dans le champ matcher. Par exemple, pour faire correspondre toutes les outils SQL, utilisez "matcher": "SQL*". Vous pouvez utiliser des expressions régulières pour faire correspondre plusieurs outils.

Écriture de scripts de hook¶

Les scripts de hook acceptent l’entrée JSON via une entrée standard et la sortie JSON via une sortie standard. La sortie contient un champ indiquant si l’opération est autorisée ou refusée. En option, le script de hook peut renvoyer une version modifiée de l’entrée de l’outil.

Exemple d’entrée :

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

Exemple de sortie :

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

Le code de retour indique s’il faut bloquer l’opération :

• 0 : Ne pas bloquer

• 2 : Bloquer

Ces informations peuvent également être renvoyées dans le cadre de la sortie JSON, comme indiqué ci-dessous.

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

Les variables d’environnement suivantes sont disponibles dans les scripts de hook :

Exemples de hook¶

Les exemples suivants illustrent la sortie possible pour les cas d’utilisation courants des hooks.

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

Bonnes pratiques en matière de hooks¶

• Maintenez la vitesse des hooks : les délais d’expiration sont de 60 secondes par défaut

• Traitez les erreurs correctement : renvoyez la sortie 0 en cas d’incertitude

• Journalisez le débogage : écrivez dans les fichiers pour la résolution des problèmes

• Utilisez des correspondances : ciblez des outils spécifiques, et non tous les outils

• Effectuez des tests avancés : utilisez le gestionnaire de hooks pour vérifier le comportement

Types de transports¶

Cortex Code prend en charge trois types de transports MCP :

Vous pouvez utiliser OAuth pour vous authentifier auprès de serveurs MCP HTTP. La première fois que vous vous connectez à un serveur configuré pour OAuth, CLI Code Cortex ouvre une fenêtre du navigateur, où l’utilisateur s’authentifie. Le jeton résultant est stocké dans ~/.snowflake/cortex/mcp_oauth/ et actualisé automatiquement selon les besoins. Voici un exemple de configuration 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"
   }
}

Gestion des serveurs MCP¶

Vous pouvez émettre la commande /mcp dans une session CLI Cortex Code interactive pour ouvrir une visionneuse d’état MCP interactive. Utilisez la commande cortex mcp pour gérer les configurations de serveurs MCP à partir de la ligne de commande.

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}

Configuration d’MCP¶

La configuration du serveur MCP est stockée dans ~/.snowflake/cortex/mcp.json sous la clé mcpServers. L’exemple suivant montre la structure d’un fichier de configuration avec un seul serveur 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"

Utilisation des outils MCP¶

Une fois configurés, les outils MCP sont disponibles automatiquement dans les sessions CLI Cortex Code. Vous les invoquez via des commandes en langage naturel :

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

Les autorisations sont demandées lors de la première utilisation. Configurez les valeurs par défaut dans ~/.snowflake/cortex/permissions.json :

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

Exemples de configurations MCP¶

Les exemples suivants illustrent les configurations de serveurs MCP pour les cas d’utilisation courants.

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

Résolution des problèmes liés au MCP¶

Serveur qui ne se connecte pas

• Vérifiez /mcp pendant une session pour s’assurer qu’il figure dans la liste

• Utilisez cortex mcp start <server> pour tester la connexion

• Vérifier que les identifiants de connexion sont correctement définis dans les variables d’environnement

• cat ~/.snowflake/cortex/logs/mcp.log pour examiner le journal à la recherche d’indices

Outils qui n’apparaissent pas

• Exécutez cortex mcp list pour vérifier la configuration

• Assurez-vous que les noms des outils sont valides (ils ne contiennent que des caractères alphanumériques, des tirets bas et des traits d’union)

• Vérifiez que les noms des outils font moins de 64 caractères

Problèmes OAuth

• Effacez les jetons mis en cache : rm ~/.snowflake/cortex/mcp_oauth/{server}*

• Reconnectez-vous pour déclencher un nouveau flux OAuth

• Vérifiez que le port de redirection est disponible (par défaut, 8585)

Variables d’environnement non développées

• Utilisez la syntaxe ${VAR} (avec des accolades) plutôt que $VAR

• Assurez-vous que la variable est définie dans votre shell (echo $VAR)

• Vérifiez les fautes de frappe dans les noms de variables

Bonnes pratiques en matière de MCP¶

• Utilisez des noms de serveurs descriptifs : clarifiez l’espace de noms des outils

• Définissez des délais d’expiration appropriés : la valeur par défaut est de 10 minutes pour la liste des outils

• Identifiants de connexion sécurisés : utilisez des variables d’environnement, et non des secrets codés en dur

• Testez les connexions : utilisez cortex mcp start avant d’utiliser un serveur