Blog

Comment Convertir un Agent IA pour Travailler dans 10 IDE Différents

Ashley Innocent

Ashley Innocent

19 March 2026

Comment Convertir un Agent IA pour Travailler dans 10 IDE Différents

enterprise.banner.title

enterprise.banner.feature1

enterprise.banner.feature2

enterprise.banner.feature3

enterprise.banner.ctaB

TL;DR

Convertissez un fichier d'agent IA en 10 IDE en 3 étapes : (1) Analysez le frontmatter YAML avec les fonctions bash get_field(), get_body() et to_kebab(), (2) Transformez vers des formats spécifiques aux outils en utilisant convert.sh (Claude Code .md, Cursor .mdc, Aider CONVENTIONS.md, Windsurf .windsurfrules), (3) Installez vers les chemins corrects avec install.sh. Écrivez une fois, convertissez automatiquement, déployez partout.

Un fichier d'agent. Dix IDE. Apprenez comment le projet The Agency convertit un seul fichier Markdown pour fonctionner avec Claude Code, Cursor, Aider, Windsurf, GitHub Copilot et plus de 6 autres outils.

Vous écrivez un agent IA. Maintenant, vous voulez qu'il soit disponible dans :

Écrivez-vous 10 versions ? Non. Vous écrivez une fois, convertissez automatiquement.

Le projet The Agency résout ce problème avec deux scripts bash :

Dans ce tutoriel, vous ferez de la rétro-ingénierie des deux scripts. Vous apprendrez à analyser le frontmatter YAML, à extraire le contenu du corps et à construire des pipelines de conversion pour n'importe quel outil.

💡
Que vous déployiez des agents pour des flux de travail de développement d'API avec l'intégration Apidog ou que vous créiez des agents de test spécialisés, le système de conversion garantit qu'ils fonctionnent sur tous les IDE préférés de votre équipe.
bouton

Le format d'agent

Chaque agent de The Agency utilise la même structure :

---
name: API Tester
description: Specialized in API testing with Apidog, Postman, and automated validation
color: purple
emoji: 🧪
vibe: Breaks APIs before users do.
---

# API Tester Agent Personality

You are **API Tester**, an expert in API validation...

## Identity & Memory
- Role: API testing specialist
- Personality: Thorough, skeptical, evidence-focused
...

Le fichier a deux parties :

  1. Frontmatter — Métadonnées YAML entre des délimiteurs ---
  2. Corps — Contenu Markdown après le second ---

La conversion signifie : extraire les champs du frontmatter, transformer le corps au format cible, écrire vers le chemin correct.

Étape 1 : Analyser le frontmatter YAML

Créez parse-frontmatter.sh :

#!/usr/bin/env bash
#
# parse-frontmatter.sh — Extract YAML frontmatter fields from agent files
#

set -euo pipefail

# Extract a single field value from YAML frontmatter
# Usage: get_field <field> <file>
get_field() {
  local field="$1" file="$2"
  awk -v f="$field" '
    /^---$/ { fm++; next }
    fm == 1 && $0 ~ "^" f ": " {
      sub("^" f ": ", "");
      print;
      exit
    }
  ' "$file"
}

# Strip frontmatter, return only body
# Usage: get_body <file>
get_body() {
  awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$1"
}

# Convert name to kebab-case slug
# Usage: to_kebab "API Tester" → api-tester
to_kebab() {
  echo "$1" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g'
}

# Demo
if [[ "${1:-}" == "--demo" ]]; then
  AGENT_FILE="${2:-test-agent.md}"
  echo "File: $AGENT_FILE"
  echo "Name: $(get_field 'name' "$AGENT_FILE")"
  echo "Description: $(get_field 'description' "$AGENT_FILE")"
  echo "Slug: $(to_kebab "$(get_field 'name' "$AGENT_FILE")")"
  echo "---"
  echo "Body preview:"
  get_body "$AGENT_FILE" | head -10
fi

Testez-le :

chmod +x parse-frontmatter.sh
./parse-frontmatter.sh --demo engineering-backend-architect.md

Sortie :

File: engineering-backend-architect.md
Name: Backend Architect
Description: Senior backend architect specializing in scalable system design...
Slug: backend-architect
---
Body preview:
# Backend Architect Agent Personality

You are **Backend Architect**, a senior backend architect...

Étape 2 : Convertir au format Claude Code

Claude Code utilise des fichiers .md bruts. Aucune conversion nécessaire — il suffit de copier :

convert_claude_code() {
  local agent_file="$1"
  local dest="$HOME/.claude/agents/"
  mkdir -p "$dest"
  cp "$agent_file" "$dest/"
  echo "  Claude Code: $(basename "$agent_file")"
}

Étape 3 : Convertir au format Cursor

Cursor utilise des fichiers .mdc avec un champ description dans le frontmatter :

convert_cursor() {
  local agent_file="$1"
  local name=$(get_field 'name' "$agent_file")
  local description=$(get_field 'description' "$agent_file")
  local slug=$(to_kebab "$name")
  local body=$(get_body "$agent_file")

  local output=".cursor/rules/agency-${slug}.mdc"
  mkdir -p "$(dirname "$output")"

  cat > "$output" << EOF
---
description: Agency agent: $description
---
$body
EOF

  echo "  Cursor: agency-${slug}.mdc"
}

Entrée :

---
name: API Tester
description: Specialized in API testing...
---

# API Tester Agent...

Sortie (.mdc) :

---
description: Agency agent: Specialized in API testing...
---

# API Tester Agent...

Étape 4 : Convertir au format Aider

Aider utilise un seul fichier CONVENTIONS.md contenant tous les agents :

convert_aider() {
  local agent_file="$1"
  local output="CONVENTIONS.md"

  # Append with separator
  echo "" >> "$output"
  echo "---" >> "$output"
  echo "" >> "$output"
  cat "$agent_file" >> "$output"

  echo "  Aider: appended to $output"
}

Construire le fichier complet :

build_aider() {
  local output="CONVENTIONS.md"
  echo "# Agency Agents for Aider" > "$output"
  echo "" >> "$output"
  echo "This file contains all Agency agents for Aider integration." >> "$output"
  echo "" >> "$output"

  for agent_file in engineering/*.md design/*.md testing/*.md; do
    convert_aider "$agent_file"
  done
}

Étape 5 : Convertir au format Windsurf

Windsurf utilise un seul fichier .windsurfrules (similaire à Aider) :

convert_windsurf() {
  local agent_file="$1"
  local output=".windsurfrules"

  echo "" >> "$output"
  echo "---" >> "$output"
  echo "" >> "$output"
  cat "$agent_file" >> "$output"

  echo "  Windsurf: appended to $output"
}

Étape 6 : Convertir au format Antigravity

Antigravity (Gemini) utilise des fichiers SKILL.md dans des sous-répertoires :

convert_antigravity() {
  local agent_file="$1"
  local name=$(get_field 'name' "$agent_file")
  local slug=$(to_kebab "$name")
  local output="integrations/antigravity/skills/agency-${slug}/SKILL.md"

  mkdir -p "$(dirname "$output")"

  cat > "$output" << EOF
# Agency Agent: $name

$(get_body "$agent_file")
EOF

  echo "  Antigravity: agency-${slug}/SKILL.md"
}

Étape 7 : Convertir au format OpenClaw

OpenClaw utilise trois fichiers par agent (SOUL.md, AGENTS.md, IDENTITY.md) :

convert_openclaw() {
  local agent_file="$1"
  local name=$(get_field 'name' "$agent_file")
  local description=$(get_field 'description' "$agent_file")
  local slug=$(to_kebab "$name")
  local body=$(get_body "$agent_file")

  local output_dir="integrations/openclaw/agency-${slug}"
  mkdir -p "$output_dir"

  # SOUL.md - Main agent definition
  cat > "$output_dir/SOUL.md" << EOF
# $name

$description

---

$body
EOF

  # AGENTS.md - Agent capabilities
  cat > "$output_dir/AGENTS.md" << EOF
# Agent Capabilities: $name

- Specialized expertise in domain
- Deliverable-focused output
- Success metrics defined

See SOUL.md for full definition.
EOF

  # IDENTITY.md - Agent identity
  cat > "$output_dir/IDENTITY.md" << EOF
# Identity: $name

- Name: $name
- Description: $description
- Source: The Agency (agency-agents repo)
EOF

  echo "  OpenClaw: agency-${slug}/"
}

Étape 8 : Le script convert.sh complet

Voici le script de conversion complet (simplifié) :

#!/usr/bin/env bash
#
# convert.sh — Convert all Agency agents to tool-specific formats
#

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
OUT_DIR="$REPO_ROOT/integrations"

# Frontmatter helpers
get_field() {
  local field="$1" file="$2"
  awk -v f="$field" '
    /^---$/ { fm++; next }
    fm == 1 && $0 ~ "^" f ": " { sub("^" f ": ", ""); print; exit }
  ' "$file"
}

get_body() {
  awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$1"
}

to_kebab() {
  echo "$1" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g'
}

# Conversion functions
convert_claude_code() {
  local agent_file="$1"
  local dest="$OUT_DIR/claude-code/"
  mkdir -p "$dest"
  cp "$agent_file" "$dest/"
}

convert_cursor() {
  local agent_file="$1"
  local name=$(get_field 'name' "$agent_file")
  local slug=$(to_kebab "$name")
  local body=$(get_body "$agent_file")

  mkdir -p "$OUT_DIR/cursor/.cursor/rules/"
  cat > "$OUT_DIR/cursor/.cursor/rules/agency-${slug}.mdc" << EOF
---
description: Agency agent: $(get_field 'description' "$agent_file")
---
$body
EOF
}

convert_aider() {
  local output="$OUT_DIR/aider/CONVENTIONS.md"
  echo "" >> "$output"
  echo "---" >> "$output"
  cat "$agent_file" >> "$output"
}

convert_windsurf() {
  local output="$OUT_DIR/windsurf/.windsurfrules"
  echo "" >> "$output"
  echo "---" >> "$output"
  cat "$agent_file" >> "$output"
}

# Main conversion loop
echo "Converting Agency agents..."

AGENT_DIRS=(engineering design testing marketing sales)

for dir in "${AGENT_DIRS[@]}"; do
  for agent_file in "$REPO_ROOT/$dir"/*.md; do
    [[ -f "$agent_file" ]] || continue

    name=$(get_field 'name' "$agent_file")
    echo "Processing: $name"

    convert_claude_code "$agent_file"
    convert_cursor "$agent_file"
  done
done

# Build combined files
echo "# Agency Agents for Aider" > "$OUT_DIR/aider/CONVENTIONS.md"
for dir in "${AGENT_DIRS[@]}"; do
  for agent_file in "$REPO_ROOT/$dir"/*.md; do
    [[ -f "$agent_file" ]] || continue
    convert_aider "$agent_file"
  done
done

echo "# Agency Agents for Windsurf" > "$OUT_DIR/windsurf/.windsurfrules"
for dir in "${AGENT_DIRS[@]}"; do
  for agent_file in "$REPO_ROOT/$dir"/*.md; do
    [[ -f "$agent_file" ]] || continue
    convert_windsurf "$agent_file"
  done
done

echo "Conversion complete!"
echo "  Claude Code: $OUT_DIR/claude-code/"
echo "  Cursor: $OUT_DIR/cursor/.cursor/rules/"
echo "  Aider: $OUT_DIR/aider/CONVENTIONS.md"
echo "  Windsurf: $OUT_DIR/windsurf/.windsurfrules"

Exécutez-le :

chmod +x convert.sh
./convert.sh

Étape 9 : Installer vers chaque outil

Après la conversion, copiez les fichiers vers les chemins spécifiques aux outils :

#!/usr/bin/env bash
#
# install.sh — Install converted agents to your local tools
#

set -euo pipefail

# Claude Code
install_claude_code() {
  local src="$REPO_ROOT/integrations/claude-code/"
  local dest="$HOME/.claude/agents/"
  mkdir -p "$dest"
  cp "$src"/*.md "$dest/"
  echo "Claude Code: $(find "$dest" -name '*.md' | wc -l) agents installed"
}

# Cursor
install_cursor() {
  local src="$REPO_ROOT/integrations/cursor/.cursor/rules/"
  local dest="./.cursor/rules/"
  mkdir -p "$dest"
  cp "$src"/*.mdc "$dest/"
  echo "Cursor: $(find "$dest" -name '*.mdc' | wc -l) rules installed"
}

# Aider
install_aider() {
  local src="$REPO_ROOT/integrations/aider/CONVENTIONS.md"
  local dest="./CONVENTIONS.md"
  cp "$src" "$dest"
  echo "Aider: CONVENTIONS.md installed"
}

# Windsurf
install_windsurf() {
  local src="$REPO_ROOT/integrations/windsurf/.windsurfrules"
  local dest="./.windsurfrules"
  cp "$src" "$dest"
  echo "Windsurf: .windsurfrules installed"
}

# Install all detected tools
install_all() {
  if [[ -d "$HOME/.claude/agents/" ]]; then
    install_claude_code
  fi
  if command -v cursor &>/dev/null || [[ -d "./.cursor/" ]]; then
    install_cursor
  fi
  if command -v aider &>/dev/null; then
    install_aider
  fi
}

install_all

Comparaison des formats

Outil Format Portée Conversion
Claude Code .md Utilisateur (~/.claude/agents/) Copie telle quelle
Cursor .mdc Projet (.cursor/rules/) Ajouter la description du frontmatter
Aider CONVENTIONS.md Racine du projet Concaténer tous les agents
Windsurf .windsurfrules Racine du projet Concaténer tous les agents
GitHub Copilot .md Utilisateur (~/.github/agents/) Copie telle quelle
Antigravity SKILL.md Utilisateur (~/.gemini/antigravity/) Encapsuler dans un répertoire de compétences
OpenClaw SOUL.md + autres Utilisateur (~/.openclaw/) Diviser en 3 fichiers
Gemini CLI Extension Utilisateur (~/.gemini/extensions/) Générer le manifeste + les compétences
OpenCode .md Projet (.opencode/agents/) Copie telle quelle
Qwen Code .md Projet (.qwen/agents/) Copier en tant que sous-agent

Créez votre propre script de conversion

Modèle pour ajouter un nouvel outil :

#!/usr/bin/env bash

# 1. Define conversion function
convert_your_tool() {
  local agent_file="$1"
  local name=$(get_field 'name' "$agent_file")
  local description=$(get_field 'description' "$agent_file")
  local slug=$(to_kebab "$name")
  local body=$(get_body "$agent_file")

  # 2. Create output path
  local output="path/to/your/tool/agency-${slug}.ext"
  mkdir -p "$(dirname "$output")"

  # 3. Write converted content
  cat > "$output" << EOF
# Your tool-specific format
# Use: $name, $description, $body
EOF

  echo "  YourTool: agency-${slug}.ext"
}

# 4. Add to main loop
for agent_file in engineering/*.md; do
  convert_your_tool "$agent_file"
done

Ce que vous avez construit

Composant Objectif
get_field() Extraire les valeurs du frontmatter YAML
get_body() Supprimer le frontmatter, retourner le corps markdown
to_kebab() Convertir les noms en slugs URL-compatibles
convert_cursor() Transformer au format .mdc
convert_aider() Concaténer en un seul fichier
convert_windsurf() Concaténer en un seul fichier
convert_antigravity() Créer des répertoires de compétences
convert_openclaw() Diviser en 3 fichiers par agent
install.sh Copier vers les chemins spécifiques aux outils

Prochaines étapes

Étendez les scripts :

Ajoutez plus d'outils :

Optimisez pour les grands dépôts :

Dépannage des problèmes courants

Le script de conversion échoue avec "mauvaise substitution" :

Les champs du frontmatter ne sont pas extraits :

La génération de slugs crée des noms corrompus :

Les règles Cursor ne se chargent pas :

Le fichier Aider CONVENTIONS.md devient trop volumineux :

Optimisation des performances pour les conversions importantes

Traitement parallèle :

Pour les dépôts avec plus de 100 agents, utilisez GNU parallel :

#!/usr/bin/env bash
# convert-parallel.sh

export OUT_DIR="$REPO_ROOT/integrations"

# Export functions for parallel use
export -f get_field get_body to_kebab convert_cursor convert_claude_code

# Find all agent files and process in parallel
find "$REPO_ROOT" -name "*.md" -type f | \
  parallel -j 8 --progress '
    name=$(get_field "name" {})
    slug=$(to_kebab "$name")
    echo "Converting: $name"
    convert_cursor "{}"
    convert_claude_code "{}"
  '

echo "Parallel conversion complete!"

Conversion incrémentielle :

Ne convertissez que les fichiers modifiés :

#!/usr/bin/env bash
# convert-incremental.sh

CACHE_FILE="$REPO_ROOT/.conversion-cache"

# Load previous state
declare -A PREV_HASHES
if [[ -f "$CACHE_FILE" ]]; then
  while IFS='=' read -r file hash; do
    PREV_HASHES["$file"]="$hash"
  done < "$CACHE_FILE"
fi

# Process each agent
for agent_file in engineering/*.md; do
  CURRENT_HASH=$(md5sum "$agent_file" | cut -d' ' -f1)
  PREV_HASH="${PREV_HASHES[$agent_file]:-}"

  if [[ "$CURRENT_HASH" != "$PREV_HASH" ]]; then
    echo "Changed: $agent_file"
    convert_cursor "$agent_file"
    convert_claude_code "$agent_file"
    NEW_HASHES["$agent_file"]="$CURRENT_HASH"
  else
    echo "Unchanged: $agent_file"
  fi
done

# Save cache
for file in "${!NEW_HASHES[@]}"; do
  echo "$file=${NEW_HASHES[$file]}"
done > "$CACHE_FILE"

Suivi de la progression :

Ajoutez une progression visuelle pour les longues conversions :

#!/usr/bin/env bash

total_files=$(find "$REPO_ROOT" -name "*.md" -type f | wc -l)
current=0

for agent_file in "$REPO_ROOT"/**/*.md; do
  ((current++))
  percent=$((current * 100 / total_files))

  # Progress bar
  filled=$((percent / 5))
  empty=$((20 - filled))
  bar=$(printf '%*s' "$filled" | tr ' ' '#')
  spaces=$(printf '%*s' "$empty" | tr ' ' ' ')

  name=$(get_field 'name' "$agent_file")
  echo -ne "\r[${bar}${spaces}] ${percent}% - $name"

  convert_cursor "$agent_file"
done

echo -ne "\n"

Considérations de sécurité pour les agents partagés

Validation des sources d'agents :

Lors du téléchargement d'agents depuis des sources externes :

#!/usr/bin/env bash
# validate-agent.sh

validate_agent() {
  local file="$1"

  # Check required frontmatter fields
  local name=$(get_field 'name' "$file")
  local description=$(get_field 'description' "$file")

  if [[ -z "$name" ]]; then
    echo "ERROR: Missing 'name' field in $file"
    return 1
  fi

  if [[ -z "$description" ]]; then
    echo "WARNING: Missing 'description' field in $file"
  fi

  # Check for malicious patterns in body
  local body=$(get_body "$file")

  if echo "$body" | grep -q 'rm -rf\|curl.*\|wget.*\|eval\|exec'; then
    echo "WARNING: Potentially dangerous patterns in $file"
    return 1
  fi

  echo "VALID: $name"
  return 0
}

Exécution d'agents en sandbox :

Pour les agents non fiables, exécutez dans des environnements isolés :

Un fichier d'agent. Dix IDE. Deux scripts bash.

C'est le pouvoir de l'automatisation de la conversion. Écrivez une fois, convertissez automatiquement, installez partout.

À votre tour : ajoutez la prise en charge de la conversion pour votre outil IA préféré. Partagez le script. Rendez les agents portables.

Points clés à retenir

bouton

FAQ

Qu'est-ce que convert.sh et comment ça marche ? convert.sh est un script bash qui analyse le frontmatter YAML des fichiers Markdown d'agent, extrait le contenu du corps et transforme chaque agent en formats spécifiques aux outils. Il utilise awk pour l'analyse, sed pour la conversion de slugs et les heredocs pour la génération de sortie.

Comment fonctionne l'analyse du frontmatter en bash ? La fonction get_field() utilise awk pour suivre les délimiteurs du frontmatter (---), trouve la ligne correspondant au nom du champ et en extrait la valeur. get_body() affiche toutes les lignes après le second délimiteur ---.

Quels IDE et outils sont pris en charge ? Claude Code (.md), Cursor (.mdc), Aider (CONVENTIONS.md), Windsurf (.windsurfrules), GitHub Copilot (.md), Antigravity (SKILL.md), OpenClaw (SOUL.md + 2 fichiers), extensions Gemini CLI, OpenCode et Qwen Code.

Comment puis-je ajouter la prise en charge de la conversion pour un nouvel outil ? Créez une fonction convert_yourtool() qui extrait les champs du frontmatter, transforme le corps au format de votre outil et écrit vers le chemin correct. Ajoutez l'appel de la fonction à la boucle de conversion principale.

Puis-je exécuter des conversions en parallèle pour un traitement plus rapide ? Oui. Utilisez xargs -P ou GNU parallel pour traiter plusieurs fichiers d'agent simultanément. Pour plus de 100 agents, la conversion parallèle peut réduire le temps d'exécution de minutes à secondes.

Comment puis-je valider l'existence des champs du frontmatter ? Ajoutez des vérifications de validation dans votre fonction de conversion : [[ -z "$name" ]] && echo "Missing name field" && exit 1. Exécutez la validation avant d'écrire les fichiers de sortie.

Que se passe-t-il si la conversion échoue pour certains agents ? Utilisez set -euo pipefail pour échouer rapidement en cas d'erreurs. Ajoutez une gestion des erreurs avec || continue pour ignorer les fichiers corrompus. Enregistrez les échecs dans un fichier séparé pour le débogage.

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger