TL;DR
Konversi satu file agen AI ke 10 IDE dalam 3 langkah:
(1) Uraikan YAML frontmatter dengan fungsi bash get_field(), get_body(), dan to_kebab(),
(2) Transformasi ke format spesifik alat menggunakan convert.sh (Claude Code .md, Cursor .mdc, Aider CONVENTIONS.md, Windsurf .windsurfrules),
(3) Instal ke jalur yang benar dengan install.sh.
Tulis sekali, konversi otomatis, sebarkan di mana saja.
Satu file agen. Sepuluh IDE. Pelajari bagaimana proyek The Agency mengonversi satu file Markdown agar berfungsi di Claude Code, Cursor, Aider, Windsurf, GitHub Copilot, dan 6+ alat lainnya.
Anda menulis sebuah agen AI. Sekarang Anda ingin agen itu tersedia di:
- Claude Code (
.mddi~/.claude/agents/) - Cursor (
.mdcdi.cursor/rules/) - Aider (
CONVENTIONS.mddi root proyek) - Windsurf (
.windsurfrules) - GitHub Copilot (
.mddi~/.github/agents/) - dan 5+ alat lainnya
Apakah Anda menulis 10 versi? Tidak. Anda menulis sekali, konversi otomatis.
Proyek The Agency menyelesaikan ini dengan dua skrip bash:
-
convert.shโ Mentransformasi file agen ke format spesifik alat -
install.shโ Menyalin file yang dikonversi ke jalur yang benar
Dalam tutorial ini, Anda akan reverse-engineer kedua skrip. Anda akan belajar cara menguraikan YAML frontmatter, mengekstrak konten body, dan membangun pipeline konversi untuk alat apa pun.
๐ก Baik Anda menyebarkan agen untuk alur kerja pengembangan API dengan integrasi Apidog atau membuat agen pengujian khusus, sistem konversi memastikan agen tersebut berfungsi di semua IDE pilihan tim Anda.
Format Agen
Setiap agen di The Agency menggunakan struktur yang sama:
---
name: API Tester
description: "Khusus dalam pengujian API dengan Apidog, Postman, dan validasi otomatis"
color: purple
emoji: ๐งช
vibe: Merusak API sebelum pengguna melakukannya.
---
# Kepribadian Agen Penguji API
Anda adalah **Penguji API**, seorang ahli dalam validasi API...
## Identitas & Memori
- Peran: Spesialis pengujian API
- Kepribadian: Teliti, skeptis, berfokus pada bukti
...
File ini terdiri dari dua bagian utama:
-
Frontmatter โ Metadata YAML di antara
--- -
Body โ Konten Markdown setelah
---kedua
Konversi berarti: mengekstrak bidang dari frontmatter, mengubah body ke format target, menulis ke jalur yang sesuai.
Langkah 1: Uraikan YAML Frontmatter
Buat skrip parse-frontmatter.sh:
#!/usr/bin/env bash
#
# parse-frontmatter.sh โ Mengekstrak bidang YAML frontmatter dari file agen
#
set -euo pipefail
# Ekstrak nilai bidang tunggal dari YAML frontmatter
get_field() {
local field="$1" file="$2"
awk -v f="$field" '
/^---$/ { fm++; next }
fm == 1 && $0 ~ "^" f ": " {
sub("^" f ": ", "");
print;
exit
}
' "$file"
}
# Hapus frontmatter, kembalikan body
get_body() {
awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$1"
}
# Konversi nama ke slug kebab-case
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 "Nama: $(get_field 'name' "$AGENT_FILE")"
echo "Deskripsi: $(get_field 'description' "$AGENT_FILE")"
echo "Slug: $(to_kebab "$(get_field 'name' "$AGENT_FILE")")"
echo "---"
echo "Pratinjau Body:"
get_body "$AGENT_FILE" | head -10
fi
Uji dengan:
chmod +x parse-frontmatter.sh
./parse-frontmatter.sh --demo engineering-backend-architect.md
Output yang diharapkan:
File: engineering-backend-architect.md
Nama: Backend Architect
Deskripsi: Arsitek backend senior yang berspesialisasi dalam desain sistem yang skalabel...
Slug: backend-architect
---
Pratinjau Body:
# Kepribadian Agen Arsitek Backend
Anda adalah **Arsitek Backend**, seorang arsitek backend senior...
Langkah 2: Konversi ke Format Claude Code
Claude Code menggunakan file .md mentah. Tidak perlu konversi, cukup salin:
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")"
}
Langkah 3: Konversi ke Format Cursor
Cursor menggunakan file .mdc dengan frontmatter description:
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: Agen agensi: $description
---
$body
EOF
echo " Cursor: agency-${slug}.mdc"
}
Input:
---
name: API Tester
description: Khusus dalam pengujian API...
---
# Agen Penguji API...
Output (.mdc):
---
description: Agen agensi: Khusus dalam pengujian API...
---
# Agen Penguji API...
Langkah 4: Konversi ke Format Aider
Aider menggabungkan semua agen ke file CONVENTIONS.md:
convert_aider() {
local agent_file="$1"
local output="CONVENTIONS.md"
# Tambahkan pemisah
echo "" >> "$output"
echo "---" >> "$output"
echo "" >> "$output"
cat "$agent_file" >> "$output"
echo " Aider: ditambahkan ke $output"
}
Bangun file gabungan:
build_aider() {
local output="CONVENTIONS.md"
echo "# Agen Agensi untuk Aider" > "$output"
echo "" >> "$output"
echo "File ini berisi semua agen Agensi untuk integrasi Aider." >> "$output"
echo "" >> "$output"
for agent_file in engineering/*.md design/*.md testing/*.md; do
convert_aider "$agent_file"
done
}
Langkah 5: Konversi ke Format Windsurf
Windsurf juga menggabungkan semua agen ke .windsurfrules:
convert_windsurf() {
local agent_file="$1"
local output=".windsurfrules"
echo "" >> "$output"
echo "---" >> "$output"
echo "" >> "$output"
cat "$agent_file" >> "$output"
echo " Windsurf: ditambahkan ke $output"
}
Langkah 6: Konversi ke Format Antigravity
Antigravity (Gemini) menggunakan file SKILL.md di subdirektori:
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
# Agen Agensi: $name
$(get_body "$agent_file")
EOF
echo " Antigravity: agency-${slug}/SKILL.md"
}
Langkah 7: Konversi ke Format OpenClaw
OpenClaw memisahkan setiap agen ke tiga file:
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
cat > "$output_dir/SOUL.md" << EOF
# $name
$description
---
$body
EOF
# AGENTS.md
cat > "$output_dir/AGENTS.md" << EOF
# Kemampuan Agen: $name
- Keahlian khusus di domain
- Output berfokus pada hasil
- Metrik keberhasilan yang ditentukan
Lihat SOUL.md untuk definisi lengkap.
EOF
# IDENTITY.md
cat > "$output_dir/IDENTITY.md" << EOF
# Identitas: $name
- Nama: $name
- Deskripsi: $description
- Sumber: The Agency (repo agen agensi)
EOF
echo " OpenClaw: agency-${slug}/"
}
Langkah 8: Skrip convert.sh Lengkap
Berikut contoh skrip konversi utama:
#!/usr/bin/env bash
#
# convert.sh โ Mengonversi semua agen Agensi ke format spesifik alat
#
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
OUT_DIR="$REPO_ROOT/integrations"
# Pembantu frontmatter
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'
}
# Fungsi konversi
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: Agen agensi: $(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"
}
# Loop konversi utama
echo "Mengonversi agen Agensi..."
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 "Memproses: $name"
convert_claude_code "$agent_file"
convert_cursor "$agent_file"
done
done
# Gabungkan file untuk Aider
echo "# Agen Agensi untuk 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
# Gabungkan file untuk Windsurf
echo "# Agen Agensi untuk 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 "Konversi selesai!"
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"
Jalankan dengan:
chmod +x convert.sh
./convert.sh
Langkah 9: Instal ke Setiap Alat
Setelah konversi, salin file ke jalur alat masing-masing:
#!/usr/bin/env bash
#
# install.sh โ Menginstal agen yang dikonversi ke alat lokal Anda
#
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) agen terinstal"
}
# 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) aturan terinstal"
}
# Aider
install_aider() {
local src="$REPO_ROOT/integrations/aider/CONVENTIONS.md"
local dest="./CONVENTIONS.md"
cp "$src" "$dest"
echo "Aider: CONVENTIONS.md terinstal"
}
# Windsurf
install_windsurf() {
local src="$REPO_ROOT/integrations/windsurf/.windsurfrules"
local dest="./.windsurfrules"
cp "$src" "$dest"
echo "Windsurf: .windsurfrules terinstal"
}
# Instal semua alat yang terdeteksi
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
Perbandingan Format
| Alat | Format | Cakupan | Konversi |
|---|---|---|---|
| Claude Code | .md |
Seluruh pengguna (~/.claude/agents/) |
Salin apa adanya |
| Cursor | .mdc |
Proyek (.cursor/rules/) |
Tambah frontmatter deskripsi |
| Aider | CONVENTIONS.md |
Root proyek | Gabungkan semua agen |
| Windsurf | .windsurfrules |
Root proyek | Gabungkan semua agen |
| GitHub Copilot | .md |
Seluruh pengguna (~/.github/agents/) |
Salin apa adanya |
| Antigravity | SKILL.md |
Seluruh pengguna (~/.gemini/antigravity/) |
Bungkus dalam direktori skill |
| OpenClaw |
SOUL.md + lainnya |
Seluruh pengguna (~/.openclaw/) |
Bagi menjadi 3 file |
| Gemini CLI | Ekstensi | Seluruh pengguna (~/.gemini/extensions/) |
Hasilkan manifes + skill |
| OpenCode | .md |
Proyek (.opencode/agents/) |
Salin apa adanya |
| Qwen Code | .md |
Proyek (.qwen/agents/) |
Salin sebagai SubAgen |
Buat Skrip Konversi Anda Sendiri
Gunakan templat berikut untuk menambah alat baru:
#!/usr/bin/env bash
# 1. Definisikan fungsi konversi
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. Buat jalur output
local output="path/to/your/tool/agency-${slug}.ext"
mkdir -p "$(dirname "$output")"
# 3. Tulis konten yang dikonversi
cat > "$output" << EOF
# Format spesifik alat Anda
# Gunakan: $name, $description, $body
EOF
echo " YourTool: agency-${slug}.ext"
}
# 4. Tambahkan ke loop utama
for agent_file in engineering/*.md; do
convert_your_tool "$agent_file"
done
Apa yang Anda Bangun
| Komponen | Tujuan |
|---|---|
get_field() |
Mengekstrak nilai YAML frontmatter |
get_body() |
Menghilangkan frontmatter, ambil body |
to_kebab() |
Membuat slug aman untuk URL |
convert_cursor() |
Transformasi ke format .mdc
|
convert_aider() |
Gabungkan ke satu file |
convert_windsurf() |
Gabungkan ke satu file |
convert_antigravity() |
Membuat direktori skill |
convert_openclaw() |
Bagi jadi 3 file per agen |
install.sh |
Salin ke jalur spesifik alat |
Langkah Selanjutnya
Perluas skrip:
- Tambahkan konversi paralel dengan
xargs -Patau GNU parallel - Tambahkan validasi (cek bidang frontmatter wajib)
- Tambahkan mode dry-run (
--dry-run)
Tambahkan lebih banyak alat:
- Ekstensi VS Code
- IDE JetBrains
- Alat internal kustom
Optimalkan untuk repositori besar:
- Cache hasil parsing frontmatter
- Gunakan
finddengan-print0untuk file dengan spasi - Tambahkan progress bar untuk 100+ agen
Memecahkan Masalah Umum
Skrip konversi gagal dengan "bad substitution":
- Jalankan dengan bash, bukan sh:
#!/usr/bin/env bash - Cek versi bash:
bash --version(harus 4.0+) - Jalankan eksplisit dengan bash:
bash convert.sh - Perbaiki baris Windows:
sed -i 's/\r$//' convert.sh
Bidang frontmatter tidak diekstrak:
- Format YAML harus
:(titik dua + spasi) - Tidak ada spasi ekstra di depan nama field
- Pembatas harus
---(3 tanda strip) - Uji parsing manual:
./parse-frontmatter.sh --demo agent.md
Pembuatan slug menghasilkan nama aneh:
- Uji
to_kebab()untuk kasus khusus - Tangani karakter khusus:
to_kebab() { echo "$1" | iconv -f utf8 -t ascii//translit | ... } - Fallback jika slug kosong:
[[ -z "$slug" ]] && slug="unknown-agent" - Log nama asli untuk debugging
Aturan Cursor tidak dimuat:
- File
.mdcwajib ada frontmatterdescription - Cek konfigurasi MCP Cursor:
.cursor/mcp.json - File harus di
.cursor/rules/, bukan.cursor/agents/ - Restart Cursor setelah menambahkan aturan baru
Aider CONVENTIONS.md terlalu besar:
- Bagi per kategori:
CONVENTIONS-engineering.md, dll - Implementasi trimming otomatis untuk agen usang
- Tambahkan TOC di bagian atas
- Pertimbangkan file per agen dengan direktif include
Optimasi Kinerja untuk Konversi Besar
Pemrosesan Paralel (GNU parallel):
#!/usr/bin/env bash
# convert-parallel.sh
export OUT_DIR="$REPO_ROOT/integrations"
# Ekspor fungsi untuk parallel
export -f get_field get_body to_kebab convert_cursor convert_claude_code
find "$REPO_ROOT" -name "*.md" -type f | \
parallel -j 8 --progress '
name=$(get_field "name" {})
slug=$(to_kebab "$name")
echo "Mengonversi: $name"
convert_cursor "{}"
convert_claude_code "{}"
'
echo "Konversi paralel selesai!"
Konversi Inkremental (hanya file berubah):
#!/usr/bin/env bash
# convert-incremental.sh
CACHE_FILE="$REPO_ROOT/.conversion-cache"
declare -A PREV_HASHES
if [[ -f "$CACHE_FILE" ]]; then
while IFS='=' read -r file hash; do
PREV_HASHES["$file"]="$hash"
done < "$CACHE_FILE"
fi
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 "Berubah: $agent_file"
convert_cursor "$agent_file"
convert_claude_code "$agent_file"
NEW_HASHES["$agent_file"]="$CURRENT_HASH"
else
echo "Tidak berubah: $agent_file"
fi
done
for file in "${!NEW_HASHES[@]}"; do
echo "$file=${NEW_HASHES[$file]}"
done > "$CACHE_FILE"
Progress Bar:
#!/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))
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"
Pertimbangan Keamanan untuk Agen Bersama
Validasi Sumber Agen:
#!/usr/bin/env bash
# validate-agent.sh
validate_agent() {
local file="$1"
# Cek field wajib
local name=$(get_field 'name' "$file")
local description=$(get_field 'description' "$file")
if [[ -z "$name" ]]; then
echo "ERROR: Bidang 'name' tidak ada di $file"
return 1
fi
if [[ -z "$description" ]]; then
echo "PERINGATAN: Bidang 'description' tidak ada di $file"
fi
# Deteksi pola berbahaya di body
local body=$(get_body "$file")
if echo "$body" | grep -q 'rm -rf\|curl.*\|wget.*\|eval\|exec'; then
echo "PERINGATAN: Pola berbahaya di $file"
return 1
fi
echo "VALID: $name"
return 0
}
Sandbox Eksekusi Agen:
- Gunakan Docker container untuk eksekusi
- Batasi akses file system (mount read-only)
- Batasi akses jaringan ke domain tertentu
- Logging semua aktivitas agen untuk audit
Satu file agen. Sepuluh IDE. Dua skrip bash.
Itulah kekuatan otomatisasi konversi. Tulis sekali, konversi otomatis, instal di mana saja.
Giliran Anda: tambahkan dukungan konversi untuk alat AI favorit Anda. Bagikan skripnya. Buat agen mudah dibawa.
Poin-Poin Penting
- Tulis sekali, konversi ke 10+ format โ Satu file Markdown dengan YAML frontmatter berubah menjadi Claude Code, Cursor, Aider, Windsurf, dan 6+ alat lainnya
-
Parsing Bash untuk ekstraksi โ
get_field()ekstrak nilai YAML,get_body()ambil body,to_kebab()buat slug URL-aman - Format alat berbeda, konversi berbeda โ Claude Code salin apa adanya, Cursor tambah frontmatter, Aider/Windsurf gabungkan seluruh agen
-
Skrip instalasi salin ke jalur alat yang benar โ Alat seluruh user pakai
~/.claude/agents/, alat proyek di.cursor/rules/atau root proyek -
Perluas dengan templat fungsi โ Definisikan
convert_your_tool(), tambahkan ke loop utama, dokumentasikan format
FAQ
Apa itu convert.sh dan bagaimana cara kerjanya?
convert.sh adalah skrip bash yang menguraikan YAML frontmatter dari file Markdown agen, mengekstrak konten body, dan mengubah setiap agen ke format spesifik alat. Ia menggunakan awk untuk parsing, sed untuk slug, dan heredoc untuk output.
Bagaimana cara kerja parsing frontmatter di bash?
get_field() menggunakan awk untuk melacak pembatas ---, menemukan baris field, dan ekstrak nilainya. get_body() mencetak baris setelah --- kedua.
IDE dan alat apa saja yang didukung?
Claude Code (.md), Cursor (.mdc), Aider (CONVENTIONS.md), Windsurf (.windsurfrules), GitHub Copilot (.md), Antigravity (SKILL.md), OpenClaw (SOUL.md + 2 file), ekstensi Gemini CLI, OpenCode, dan Qwen Code.
Bagaimana menambah dukungan alat baru?
Buat fungsi convert_yourtool() yang ekstrak frontmatter, ubah body ke format alat, dan tulis ke jalur yang sesuai. Tambahkan ke loop utama.
Bisakah konversi dijalankan paralel?
Ya, gunakan xargs -P atau GNU parallel. Untuk 100+ agen, paralel bisa memangkas waktu proses dari menit ke detik.
Bagaimana validasi field frontmatter?
Tambahkan check di fungsi: [[ -z "$name" ]] && echo "Bidang nama tidak ada" && exit 1. Jalankan validasi sebelum tulis output.
Bagaimana jika konversi gagal per agent?
Pakai set -euo pipefail untuk fail fast. Gunakan || continue untuk skip file rusak. Log kegagalan ke file terpisah untuk debugging.
Top comments (0)