要点
AIエージェントファイルを1つ書くだけで、10種類のIDEに3ステップで自動対応できます。本記事では、YAMLフロントマター解析用のget_field()・get_body()・to_kebab()関数の実装、各ツール向けフォーマットへの変換（Claude Code .md、Cursor .mdc、Aider CONVENTIONS.md、Windsurf .windsurfrulesなど）、インストール用install.shスクリプトによる配置まで、実装重視で解説します。
1つのエージェントファイルから、10種類のIDE対応ファイルを自動生成。The Agencyプロジェクトを使い、単一MarkdownからClaude Code、Cursor、Aider、Windsurf、GitHub Copilot他6種以上のツールで動作可能にする方法を解説します。
対応する場所・ファイル例
- Claude Code（
~/.claude/agents/配下.md） - Cursor（
.cursor/rules/配下.mdc） - Aider（ルートの
CONVENTIONS.md） - Windsurf（ルートの
.windsurfrules） - GitHub Copilot（
~/.github/agents/配下.md） - 他5種以上
10種類のバージョンを手動作成する必要はありません。1回書くだけで自動変換できます。
変換自動化の仕組み
The Agencyプロジェクトは、2つのbashスクリプトで変換とインストールを自動化します。
-
convert.sh… エージェントファイルをツール固有フォーマットに変換 -
install.sh… 変換済みファイルを所定パスにコピー
本記事では、YAMLフロントマターのパースから各フォーマットへの変換、インストールまでの全工程・スクリプトを実装例とともに解説します。
💡 API開発ワークフローのためにApidog統合を伴うエージェントをデプロイしたい場合でも、テスト専用エージェントを作成したい場合でも、この変換システムを使えば、全てのIDEで利用可能です。
エージェントファイルのフォーマット
The Agencyエージェントファイルは下記の構成です。
---
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
...
-
フロントマター：
---で囲まれたYAMLメタデータ -
本文：2番目の
---以降のMarkdown
変換は「フロントマター抽出→本文抽出→ツール毎に整形→正しいパスに出力」の流れです。
ステップ1：YAMLフロントマターの解析
parse-frontmatter.shを作成します。
#!/usr/bin/env bash
set -euo pipefail
# フロントマターの値を抽出
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"
}
# 名前をkebab-caseに変換
to_kebab() {
echo "$1" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g'
}
# デモ
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
テスト：
chmod +x parse-frontmatter.sh
./parse-frontmatter.sh --demo engineering-backend-architect.md
出力例：
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...
ステップ2：Claude Codeフォーマットへの変換
Claude Codeは.mdファイルをそのままコピー。
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")"
}
ステップ3：Cursorフォーマットへの変換
Cursor用にdescriptionフロントマターを持つ.mdcファイルを生成。
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"
}
入力例:
---
name: API Tester
description: Specialized in API testing...
---
# API Tester Agent...
出力例 (.mdc):
---
description: Agency agent: Specialized in API testing...
---
# API Tester Agent...
ステップ4：Aiderフォーマットへの変換
Aider用に全エージェントをCONVENTIONS.mdで連結。
convert_aider() {
local agent_file="$1"
local output="CONVENTIONS.md"
echo "" >> "$output"
echo "---" >> "$output"
echo "" >> "$output"
cat "$agent_file" >> "$output"
echo " Aider: appended to $output"
}
# 全エージェント連結例
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
}
ステップ5：Windsurfフォーマットへの変換
Aider同様、.windsurfrulesで全エージェントを連結。
convert_windsurf() {
local agent_file="$1"
local output=".windsurfrules"
echo "" >> "$output"
echo "---" >> "$output"
echo "" >> "$output"
cat "$agent_file" >> "$output"
echo " Windsurf: appended to $output"
}
ステップ6：Antigravityフォーマットへの変換
サブディレクトリにSKILL.mdを生成。
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"
}
ステップ7：OpenClawフォーマットへの変換
OpenClawはエージェントごとに3ファイル生成。
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
# Agent Capabilities: $name
- Specialized expertise in domain
- Deliverable-focused output
- Success metrics defined
See SOUL.md for full definition.
EOF
# IDENTITY.md
cat > "$output_dir/IDENTITY.md" << EOF
# Identity: $name
- Name: $name
- Description: $description
- Source: The Agency (agency-agents repo)
EOF
echo " OpenClaw: agency-${slug}/"
}
ステップ8：convert.sh 全体例
全自動変換スクリプト例（簡易・実用向け）
#!/usr/bin/env bash
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() { ... }
get_body() { ... }
to_kebab() { ... }
# Conversion functions
convert_claude_code() { ... }
convert_cursor() { ... }
convert_aider() { ... }
convert_windsurf() { ... }
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
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"
実行：
chmod +x convert.sh
./convert.sh
ステップ9：各ツールへのインストール
変換後ファイルを各ツールの所定パスに配置します。
#!/usr/bin/env bash
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() {
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
フォーマット比較
| ツール | フォーマット | スコープ | 変換 |
|---|---|---|---|
| Claude Code | .md |
ユーザー全体 | そのままコピー |
| Cursor | .mdc |
プロジェクト | descriptionフロントマター追加 |
| Aider | CONVENTIONS.md |
プロジェクトルート | 連結 |
| Windsurf | .windsurfrules |
プロジェクトルート | 連結 |
| GitHub Copilot | .md |
ユーザー全体 | そのままコピー |
| Antigravity | SKILL.md |
ユーザー全体 | スキルディレクトリにラッピング |
| OpenClaw |
SOUL.md+他 |
ユーザー全体 | 3ファイルに分割 |
| Gemini CLI | 拡張機能 | ユーザー全体 | マニフェスト+スキル生成 |
| OpenCode | .md |
プロジェクト | そのままコピー |
| Qwen Code | .md |
プロジェクト | SubAgentとしてコピー |
独自の変換スクリプトを追加したい場合
新ツール追加のテンプレート例：
#!/usr/bin/env bash
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")
local output="path/to/your/tool/agency-${slug}.ext"
mkdir -p "$(dirname "$output")"
cat > "$output" << EOF
# Your tool-specific format
# Use: $name, $description, $body
EOF
echo " YourTool: agency-${slug}.ext"
}
for agent_file in engineering/*.md; do
convert_your_tool "$agent_file"
done
構築したものまとめ
| コンポーネント | 目的 |
|---|---|
get_field() |
YAMLフロントマターの値抽出 |
get_body() |
本文抽出 |
to_kebab() |
スラッグ生成 |
convert_cursor() |
.mdcフォーマット生成 |
convert_aider() |
全エージェント連結 |
convert_windsurf() |
全エージェント連結 |
convert_antigravity() |
スキルディレクトリ生成 |
convert_openclaw() |
エージェント毎に3分割ファイル生成 |
install.sh |
ツール毎の所定パスにコピー |
次のステップ
スクリプト拡張例:
-
xargs -PやGNU parallelによる並列変換 - 必須フロントマター検証の追加
-
--dry-runフラグによるドライラン対応
さらなるツール追加例:
- VS Code拡張
- JetBrains IDE
- 社内独自ツール
大規模リポジトリ向け最適化例:
- 解析済みフロントマターキャッシュ
-
find+-print0による安全処理 - プログレスバー表示
トラブルシューティング
「bad substitution」エラー時:
-
#!/usr/bin/env bashでbash明示 - bashバージョン4.0以上か確認：
bash --version -
bash convert.shで明示的実行 - Windows改行対策：
sed -i 's/\r$//' convert.sh
フロントマター抽出失敗時:
-
:（コロン+スペース）形式か確認 - フィールド名前スペースなし確認
- 区切り文字が
---か確認 -
./parse-frontmatter.sh --demo agent.mdで手動チェック
スラッグ生成ミス時:
-
to_kebab()をエッジケースでテスト - 特殊文字は
iconv活用例：to_kebab() { echo "$1" | iconv -f utf8 -t ascii//translit | ... } - 空スラッグは
unknown-agentなどでフォールバック
Cursorルールが読み込まれない場合:
-
.mdc冒頭にdescriptionありか -
.cursor/mcp.json設定確認 -
.cursor/rules/配下か - 追加後Cursor再起動
AiderのCONVENTIONS.md肥大化時:
- カテゴリ別分割（例：
CONVENTIONS-engineering.md） - 非推奨エージェントの自動削除
- 目次追加
- 各エージェントファイルの
include指示検討
大規模変換パフォーマンス最適化
並列処理例（GNU parallel利用）:
#!/usr/bin/env bash
export OUT_DIR="$REPO_ROOT/integrations"
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 "Converting: $name"
convert_cursor "{}"
convert_claude_code "{}"
'
echo "Parallel conversion complete!"
増分変換例:
#!/usr/bin/env bash
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 "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
for file in "${!NEW_HASHES[@]}"; do
echo "$file=${NEW_HASHES[$file]}"
done > "$CACHE_FILE"
プログレスバー表示例:
#!/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"
共有エージェントのセキュリティ考慮
エージェントソース検証例:
#!/usr/bin/env bash
validate_agent() {
local file="$1"
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
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
}
信頼性が低いエージェントの安全実行:
- Dockerなどでサンドボックス実行
- 読み取り専用ファイルシステム
- ネットワークアクセス制限
- 監査ログ記録
1つのエージェントファイル。10のIDE。2つのbashスクリプト。
この自動化により、一度書けばどこにでも自動変換・設置できます。
ぜひあなたのAIツール用変換を追加、スクリプトの共有・改善を！
主要なポイント
一度書けば10以上のフォーマットに変換可能
単一Markdown（YAMLフロントマター付）から多種ツール用ファイルを自動生成。Bash解析でフロントマター抽出
get_field()でYAML抽出、get_body()で本文抽出、to_kebab()でスラッグ化。各ツールに特化した変換
Claude Codeはコピー、Cursorはdescription追加、Aider/Windsurfは全エージェント連結。インストールスクリプトで所定パス配置
ユーザー全体用は~/.claude/agents/、プロジェクト用は.cursor/rules/等。新ツール追加もテンプレートで簡単拡張
convert_your_tool()を定義しループに追加・管理。
よくある質問
Q. convert.shとは？
A. エージェントMarkdownからYAMLフロントマターをbash/awkで解析し、各ツール向けに自動変換・出力するスクリプトです。
Q. bashでのフロントマター解析の仕組みは？
A. get_field()でawkにより区切りを検出し指定フィールド値を抽出。get_body()で2つ目の---以降を出力。
Q. サポートIDEやツールは？
A. Claude Code、Cursor、Aider、Windsurf、GitHub Copilot、Antigravity、OpenClaw、Gemini CLI、OpenCode、Qwen Code他。
Q. 新ツール対応は？
A. convert_yourtool()関数でフロントマター抽出～整形しメインループに追加するだけ。
Q. 並列変換は可能か？
A. 可能です。xargs -PやGNU parallelで数百ファイルも高速処理できます。
Q. フロントマター必須チェックは？
A. [[ -z "$name" ]] && echo "Missing name field" && exit 1など検証を追加。
Q. 変換失敗時の挙動は？
A. set -euo pipefailで即エラー終了。|| continueやログで失敗ファイルも管理可能。
実践的なスクリプト例をもとに、あなたの開発フローに簡単導入できます。変換自動化で複数IDE・AIツールにエージェントを一括展開しましょう！
Top comments (0)