Cách Chuyển Đổi Một AI Agent Hoạt Động Trên 10 IDE Khác Nhau

TÓM LƯỢC

Chuyển đổi một tệp tác nhân AI sang 10 IDE trong 3 bước: (1) Phân tích YAML frontmatter bằng các hàm bash get_field(), get_body() và to_kebab(), (2) Chuyển đổi sang định dạng dành riêng cho công cụ bằng convert.sh (Claude Code .md, Cursor .mdc, Aider CONVENTIONS.md, Windsurf .windsurfrules), (3) Cài đặt vào các đường dẫn chính xác bằng install.sh. Viết một lần, tự động chuyển đổi, triển khai mọi nơi.

Một tệp tác nhân. Mười IDE. Tìm hiểu cách dự án The Agency chuyển đổi một tệp Markdown duy nhất để hoạt động trên Claude Code, Cursor, Aider, Windsurf, GitHub Copilot và hơn 6 công cụ khác.

Bạn viết một tác nhân AI. Giờ đây, bạn muốn nó khả dụng trong:

Claude Code (tệp .md trong ~/.claude/agents/)
Cursor (tệp .mdc trong .cursor/rules/)
Aider (một tệp CONVENTIONS.md duy nhất trong thư mục gốc của dự án)
Windsurf (một tệp .windsurfrules duy nhất)
GitHub Copilot (tệp .md trong ~/.github/agents/)
Và hơn 5 công cụ khác

Bạn có viết 10 phiên bản không? Không. Bạn viết một lần, tự động chuyển đổi.

Dự án The Agency giải quyết vấn đề này bằng hai tập lệnh bash:

convert.sh — Chuyển đổi tệp tác nhân sang định dạng dành riêng cho công cụ
install.sh — Sao chép các tệp đã chuyển đổi sang các đường dẫn chính xác

Trong hướng dẫn này, bạn sẽ phân tích ngược cả hai tập lệnh. Bạn sẽ học cách phân tích YAML frontmatter, trích xuất nội dung phần thân và xây dựng các quy trình chuyển đổi cho bất kỳ công cụ nào.

💡

Cho dù bạn đang triển khai tác nhân cho quy trình làm việc phát triển API với tích hợp Apidog hay tạo các tác nhân kiểm thử chuyên biệt, hệ thống chuyển đổi đảm bảo chúng hoạt động trên tất cả các IDE ưa thích của nhóm bạn.

button

Định dạng Tác nhân

Mọi tác nhân trong The Agency đều sử dụng cùng một cấu trúc:

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

Tệp có hai phần:

Frontmatter — Siêu dữ liệu YAML giữa các dấu phân cách ---
Body — Nội dung Markdown sau dấu --- thứ hai

Chuyển đổi nghĩa là: trích xuất các trường frontmatter, chuyển đổi phần thân sang định dạng đích, ghi vào đường dẫn chính xác.

Bước 1: Phân tích YAML Frontmatter

Tạo 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

Kiểm tra nó:

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

Đầu ra:

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

Bước 2: Chuyển đổi sang Định dạng Claude Code

Claude Code sử dụng các tệp .md thô. Không cần chuyển đổi — chỉ cần sao chép:

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

Bước 3: Chuyển đổi sang Định dạng Cursor

Cursor sử dụng các tệp .mdc với trường description trong 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"
}

Đầu vào:

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

# API Tester Agent...

Đầu ra (.mdc):

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

# API Tester Agent...

Bước 4: Chuyển đổi sang Định dạng Aider

Aider sử dụng một tệp CONVENTIONS.md duy nhất chứa tất cả các tác nhân:

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

Xây dựng tệp hoàn chỉnh:

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
}

Bước 5: Chuyển đổi sang Định dạng Windsurf

Windsurf sử dụng một tệp .windsurfrules duy nhất (tương tự như 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""
}

Bước 6: Chuyển đổi sang Định dạng Antigravity

Antigravity (Gemini) sử dụng các tệp SKILL.md trong các thư mục con:

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

Bước 7: Chuyển đổi sang Định dạng OpenClaw

OpenClaw sử dụng ba tệp cho mỗi tác nhân (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}/"
}

Bước 8: Toàn bộ tập lệnh convert.sh

Đây là tập lệnh chuyển đổi hoàn chỉnh (đã đơn giản hóa):

#!/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"

Chạy nó:

chmod +x convert.sh
./convert.sh

Bước 9: Cài đặt vào từng công cụ

Sau khi chuyển đổi, sao chép các tệp vào các đường dẫn dành riêng cho công cụ:

#!/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

So sánh Định dạng

Công cụ	Định dạng	Phạm vi	Chuyển đổi
Claude Code	`.md`	Toàn hệ thống người dùng (`~/.claude/agents/`)	Sao chép nguyên trạng
Cursor	`.mdc`	Dự án (`.cursor/rules/`)	Thêm description frontmatter
Aider	`CONVENTIONS.md`	Thư mục gốc dự án	Nối tất cả tác nhân
Windsurf	`.windsurfrules`	Thư mục gốc dự án	Nối tất cả tác nhân
GitHub Copilot	`.md`	Toàn hệ thống người dùng (`~/.github/agents/`)	Sao chép nguyên trạng
Antigravity	`SKILL.md`	Toàn hệ thống người dùng (`~/.gemini/antigravity/`)	Đóng gói trong thư mục kỹ năng
OpenClaw	`SOUL.md` + các tệp khác	Toàn hệ thống người dùng (`~/.openclaw/`)	Chia thành 3 tệp
Gemini CLI	Tiện ích mở rộng	Toàn hệ thống người dùng (`~/.gemini/extensions/`)	Tạo manifest + kỹ năng
OpenCode	`.md`	Dự án (`.opencode/agents/`)	Sao chép nguyên trạng
Qwen Code	`.md`	Dự án (`.qwen/agents/`)	Sao chép dưới dạng SubAgent

Xây dựng Tập lệnh Chuyển đổi của riêng bạn

Mẫu để thêm công cụ mới:

#!/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

Những gì bạn đã xây dựng

Thành phần	Mục đích
`get_field()`	Trích xuất giá trị YAML frontmatter
`get_body()`	Loại bỏ frontmatter, trả về phần thân markdown
`to_kebab()`	Chuyển đổi tên thành slug an toàn cho URL
`convert_cursor()`	Chuyển đổi sang định dạng `.mdc`
`convert_aider()`	Nối vào một tệp duy nhất
`convert_windsurf()`	Nối vào một tệp duy nhất
`convert_antigravity()`	Tạo thư mục kỹ năng
`convert_openclaw()`	Chia thành 3 tệp cho mỗi tác nhân
`install.sh`	Sao chép vào các đường dẫn dành riêng cho công cụ

Các bước tiếp theo

Mở rộng các tập lệnh:

Thêm chuyển đổi song song bằng xargs -P hoặc GNU parallel
Thêm xác thực (kiểm tra các trường frontmatter bắt buộc)
Thêm chế độ chạy thử (--dry-run)

Thêm nhiều công cụ hơn:

Tiện ích mở rộng VS Code
IDE của JetBrains
Các công cụ nội bộ tùy chỉnh

Tối ưu hóa cho các kho lưu trữ lớn:

Lưu vào bộ đệm frontmatter đã phân tích
Sử dụng find với -print0 để xử lý tệp an toàn
Thêm thanh tiến độ cho hơn 100 tác nhân

Khắc phục các sự cố thường gặp

Tập lệnh chuyển đổi bị lỗi với “bad substitution”:

Đảm bảo bạn đang chạy bash, không phải sh: #!/usr/bin/env bash
Kiểm tra phiên bản bash: bash --version (phải là 4.0+)
Chạy rõ ràng bằng bash: bash convert.sh
Tìm các ký tự xuống dòng của Windows: sed -i 's/\r$//' convert.sh

Các trường frontmatter không được trích xuất:

Xác minh định dạng YAML sử dụng : (dấu cách sau dấu hai chấm) chứ không phải chỉ :
Kiểm tra các khoảng trắng thừa trước tên trường
Đảm bảo các dấu phân cách frontmatter chính xác là --- (3 dấu gạch ngang)
Kiểm tra phân tích cú pháp thủ công: ./parse-frontmatter.sh --demo agent.md

Tạo slug tạo ra các tên bị lỗi:

Kiểm tra hàm to_kebab() với các trường hợp ngoại lệ
Xử lý các ký tự đặc biệt: to_kebab() { echo "$1" | iconv -f utf8 -t ascii//translit | ... }
Thêm dự phòng cho các slug trống: [[ -z "$slug" ]] && slug="unknown-agent"
Ghi lại tên gốc để gỡ lỗi

Quy tắc Cursor không tải được:

Xác minh các tệp .mdc có frontmatter hợp lệ với description
Kiểm tra cấu hình MCP của Cursor: .cursor/mcp.json
Đảm bảo các tệp nằm trong .cursor/rules/ chứ không phải .cursor/agents/
Khởi động lại Cursor sau khi thêm quy tắc mới

CONVENTIONS.md của Aider trở nên quá lớn:

Chia theo danh mục: CONVENTIONS-engineering.md, CONVENTIONS-design.md
Triển khai cắt tỉa tự động cho các tác nhân không dùng nữa
Thêm mục lục ở đầu
Cân nhắc các tệp cho từng tác nhân với chỉ thị include

Tối ưu hóa hiệu suất cho các chuyển đổi lớn

Xử lý song song:

Đối với các kho lưu trữ có hơn 100 tác nhân, hãy sử dụng 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!"

Chuyển đổi tăng dần:

Chỉ chuyển đổi các tệp đã thay đổi:

#!/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"

Theo dõi tiến độ:

Thêm tiến độ trực quan cho các chuyển đổi kéo dài:

#!/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"

Các cân nhắc bảo mật cho tác nhân được chia sẻ

Xác thực nguồn tác nhân:

Khi tải tác nhân từ các nguồn bên ngoài:

#!/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
}

Chạy tác nhân trong môi trường hộp cát (sandbox):

Đối với các tác nhân không đáng tin cậy, hãy chạy trong môi trường biệt lập:

Sử dụng vùng chứa Docker để thực thi tác nhân
Hạn chế quyền truy cập hệ thống tệp bằng các gắn kết chỉ đọc
Hạn chế quyền truy cập mạng vào các miền cụ thể
Ghi lại tất cả hành động của tác nhân để kiểm tra

Một tệp tác nhân. Mười IDE. Hai tập lệnh bash.

Đó là sức mạnh của tự động hóa chuyển đổi. Viết một lần, tự động chuyển đổi, cài đặt mọi nơi.

Đến lượt bạn: thêm hỗ trợ chuyển đổi cho công cụ AI yêu thích của bạn. Chia sẻ tập lệnh. Giúp các tác nhân di động.

Những điểm chính

Viết một lần, chuyển đổi sang hơn 10 định dạng — Tệp Markdown duy nhất với YAML frontmatter chuyển đổi thành Claude Code, Cursor, Aider, Windsurf và hơn 6 công cụ khác
Phân tích cú pháp Bash xử lý việc trích xuất frontmatter — get_field() trích xuất giá trị YAML, get_body() loại bỏ frontmatter, to_kebab() tạo slug an toàn cho URL
Các định dạng dành riêng cho công cụ yêu cầu các chuyển đổi khác nhau — Claude Code sao chép nguyên trạng, Cursor thêm description frontmatter, Aider/Windsurf nối tất cả tác nhân
Các tập lệnh cài đặt sao chép vào các đường dẫn chính xác — Các công cụ toàn hệ thống người dùng sử dụng ~/.claude/agents/, các công cụ dự án sử dụng .cursor/rules/ hoặc các tệp gốc dự án
Mở rộng bằng các mẫu cho các công cụ mới — Định nghĩa hàm convert_your_tool(), thêm vào vòng lặp chính, ghi lại các yêu cầu định dạng

button

Câu hỏi thường gặp

convert.sh là gì và nó hoạt động như thế nào? convert.sh là một tập lệnh bash phân tích YAML frontmatter từ các tệp Markdown tác nhân, trích xuất nội dung phần thân và chuyển đổi mỗi tác nhân sang các định dạng dành riêng cho công cụ. Nó sử dụng awk để phân tích cú pháp, sed để chuyển đổi slug và heredoc để tạo đầu ra.

Phân tích cú pháp frontmatter trong bash hoạt động như thế nào? Hàm get_field() sử dụng awk để theo dõi các dấu phân cách frontmatter (---), tìm dòng khớp với tên trường và trích xuất giá trị. get_body() in tất cả các dòng sau dấu phân cách --- thứ hai.

Các IDE và công cụ nào được hỗ trợ? Claude Code (.md), Cursor (.mdc), Aider (CONVENTIONS.md), Windsurf (.windsurfrules), GitHub Copilot (.md), Antigravity (SKILL.md), OpenClaw (SOUL.md + 2 tệp), tiện ích mở rộng Gemini CLI, OpenCode và Qwen Code.

Làm cách nào để thêm hỗ trợ chuyển đổi cho một công cụ mới? Tạo một hàm convert_yourtool() trích xuất các trường frontmatter, chuyển đổi phần thân sang định dạng của công cụ của bạn và ghi vào đường dẫn chính xác. Thêm lệnh gọi hàm vào vòng lặp chuyển đổi chính.

Tôi có thể chạy chuyển đổi song song để xử lý nhanh hơn không? Có. Sử dụng xargs -P hoặc GNU parallel để xử lý nhiều tệp tác nhân cùng lúc. Đối với hơn 100 tác nhân, chuyển đổi song song có thể giảm thời gian chạy từ vài phút xuống vài giây.

Làm cách nào để xác thực rằng các trường frontmatter tồn tại? Thêm kiểm tra xác thực trong hàm chuyển đổi của bạn: [[ -z "$name" ]] && echo "Thiếu trường tên" && exit 1. Chạy xác thực trước khi ghi tệp đầu ra.

Nếu chuyển đổi không thành công đối với một số tác nhân thì sao? Sử dụng set -euo pipefail để dừng nhanh khi có lỗi. Thêm xử lý lỗi với || continue để bỏ qua các tệp bị lỗi. Ghi lại các lỗi vào một tệp riêng để gỡ lỗi.