multi-harness-portability

マルチハーネス対応

googleadsagent.ai™によるAgent Skills™の一部です

説明

マルチハーネス対応とは、Claude Code、Cursor、Codex、Gemini CLI、OpenCode など、主要な AI コーディングハーネスすべてで動作するエージェントスキル、プロンプト、設定を作成するエンジニアリングの手法です。AI ツールの状況は急速に分断されつつあり、チームごとに異なるエディター、異なる CLI ツール、異なるモデルを使用しています。単一のプラットフォームに固定されたスキルは負担となりますが、移植可能なスキルは組織全体で価値を積み重ねる資産になります。

このスキルには、googleadsagent.ai™によるAgent Skills™向けに開発された移植性アーキテクチャが盛り込まれています。このリポジトリ内のすべてのスキルは、主要なハーネスすべてで機能するように設計されています。重要な洞察は、移植性は後付けではなく、アーキテクチャ上の決定事項だということです。これを実現するには、プラットフォーム固有の機能（フック、ルール、指示、システムプロンプト）を汎用的なスキルインターフェースに対応付ける抽象化レイヤーと、その変換を担うプラットフォーム固有のアダプターが必要です。

移植性レイヤーは、プラットフォーム間の違いを3つのカテゴリで扱います。スキルの読み込み（スキルをエージェントのコンテキストに取り込む方法）、ツールへのアクセス（利用可能なツールとその呼び出し方法）、出力形式（エージェントが結果を提供する方法）です。各カテゴリには個別のアダプターパターンが必要であり、それらを組み合わせることで、真の「一度書けばどこでも実行できる」エージェントスキルを実現します。

使用する場面

• チームで複数の AI コーディングツール（Claude Code、Cursor、Codex など）を使用している
• すべてのプラットフォームに対応する単一のスキルリポジトリを維持したい
• あるプラットフォーム向けに開発したスキルを、ほかのプラットフォームにも移植する必要がある
• コミュニティ向けのオープンソースのスキルライブラリを構築している
• CI/CD パイプラインで、複数のプラットフォームにわたってスキルを検証する必要がある
• 組織のポリシーで、プラットフォームに依存しないツールが求められている

仕組み

graph TD
    A[Universal SKILL.md] --> B[Platform Detector]
    B --> C{Which Harness?}
    C -->|Claude Code| D[Claude Adapter]
    C -->|Cursor| E[Cursor Adapter]
    C -->|Codex| F[Codex Adapter]
    C -->|Gemini| G[Gemini Adapter]
    D --> H[CLAUDE.md Rules + Hooks]
    E --> I[.cursor/rules/ + Skills]
    F --> J[codex instructions]
    G --> K[System Prompt Config]
    H --> L[Unified Execution]
    I --> L
    J --> L
    K --> L

移植性レイヤーは、汎用的なスキル定義（SKILL.md）とプラットフォーム固有の読み込みメカニズムの間に位置します。プラットフォーム検出機能が現在の実行環境を特定します。プラットフォームアダプターは、汎用的なスキル形式を各ハーネスのネイティブ設定に変換します。Claude Code は CLAUDE.md とフックを、Cursor は .cursor/rules/ と SKILL.md ファイルを、Codex は指示ファイルを使用し、Gemini はシステムプロンプトの設定を使用します。統合実行レイヤーにより、読み込み方法にかかわらず、エージェントが同等の指示と制約を受け取れるようになります。

実装

プラットフォームの検出：

#!/bin/bash
detect_platform() {
  if [ -n "$CLAUDE_CODE" ] || [ -f "CLAUDE.md" ]; then
    echo "claude-code"
  elif [ -d ".cursor" ] || [ -n "$CURSOR_SESSION" ]; then
    echo "cursor"
  elif [ -n "$CODEX_SESSION" ] || [ -f ".codex/instructions.md" ]; then
    echo "codex"
  elif [ -n "$GEMINI_CLI" ]; then
    echo "gemini"
  else
    echo "generic"
  fi
}

汎用スキルインストーラー：

import os
import shutil
from pathlib import Path

class SkillInstaller:
    PLATFORM_CONFIGS = {
        "claude-code": {
            "skill_dir": ".",
            "rules_file": "CLAUDE.md",
            "hooks_dir": ".claude/hooks",
            "format": "markdown_rules",
        },
        "cursor": {
            "skill_dir": ".cursor/skills",
            "rules_file": ".cursor/rules/{name}.md",
            "hooks_dir": None,
            "format": "skill_md",
        },
        "codex": {
            "skill_dir": ".codex",
            "rules_file": ".codex/instructions.md",
            "hooks_dir": None,
            "format": "instructions",
        },
        "gemini": {
            "skill_dir": ".gemini",
            "rules_file": ".gemini/system_prompt.md",
            "hooks_dir": None,
            "format": "system_prompt",
        },
    }

    def install(self, skill_path: str, platform: str, project_root: str):
        config = self.PLATFORM_CONFIGS[platform]
        skill = self.parse_skill(skill_path)

        if config["format"] == "markdown_rules":
            self.install_claude_code(skill, config, project_root)
        elif config["format"] == "skill_md":
            self.install_cursor(skill, config, project_root)
        elif config["format"] == "instructions":
            self.install_codex(skill, config, project_root)
        elif config["format"] == "system_prompt":
            self.install_gemini(skill, config, project_root)

    def install_cursor(self, skill, config, root):
        skill_dir = Path(root) / config["skill_dir"] / skill["name"]
        skill_dir.mkdir(parents=True, exist_ok=True)
        (skill_dir / "SKILL.md").write_text(skill["content"])

    def install_claude_code(self, skill, config, root):
        claude_md = Path(root) / config["rules_file"]
        existing = claude_md.read_text() if claude_md.exists() else ""
        section = f"\n\n## Skill: {skill['name']}\n\n{skill['instructions']}\n"
        if skill["name"] not in existing:
            claude_md.write_text(existing + section)

    def parse_skill(self, path: str) -> dict:
        content = Path(path).read_text()
        name = content.split("\n")[0].replace("# ", "").strip()
        return {"name": name, "content": content, "instructions": self.extract_instructions(content)}

    def extract_instructions(self, content: str) -> str:
        sections = content.split("\n## ")
        for section in sections:
            if section.startswith("Use When") or section.startswith("Best Practices"):
                return section
        return content[:2000]

クロスプラットフォームのスキルテスト：

# .github/workflows/skill-test.yml
name: Skill Portability Test
on: [push, pull_request]

jobs:
  test-skills:
    strategy:
      matrix:
        platform: [claude-code, cursor, codex, gemini]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install skill for ${{ matrix.platform }}
        run: |
          python scripts/install_skill.py \
            --skill skills/claude-mythos/context-engineering/SKILL.md \
            --platform ${{ matrix.platform }} \
            --root ./test-project
      - name: Validate installation
        run: |
          python scripts/validate_installation.py \
            --platform ${{ matrix.platform }} \
            --root ./test-project
      - name: Run platform-specific checks
        run: |
          python scripts/platform_checks.py \
            --platform ${{ matrix.platform }} \
            --root ./test-project

移植可能なスキルのテンプレート：

# {Skill Name}

Part of [Agent Skills™](https://github.com/itallstartedwithaidea/agent-skills)




## Description
{Platform-agnostic description using no platform-specific terminology}

## Use When
{Conditions that apply regardless of platform}

## Implementation
{Code examples using standard libraries, no platform-specific APIs}

## Platform Notes
| Platform | Loading | Notes |
|---|---|---|
| Claude Code | CLAUDE.md / hooks | {specific guidance} |
| Cursor | .cursor/skills/ | {specific guidance} |
| Codex | instructions.md | {specific guidance} |
| Gemini | system_prompt | {specific guidance} |

ベストプラクティス

1. まずプラットフォームに依存しない指示を書く — 中核となるスキルのロジックでは、プラットフォーム固有の用語を使わないでください。変換はプラットフォームアダプターが担います。
2. 少なくとも2つのプラットフォームでテストする — 移植性に関するバグは、複数のプラットフォームで実際にスキルを実行して初めて見つかります。CI による検証が不可欠です。
3. SKILL.md 形式を汎用的なソースとして使用する — 最も広くサポートされている形式です。ほかの形式はすべて、これを基に生成します。
4. プラットフォーム固有の制限事項を文書化する — ある機能にフック（Claude Code のみ）や拡張機能（Cursor のみ）が必要な場合は、互換性表に明記してください。
5. ツール固有の前提を避ける — すべてのプラットフォームで同じツールが使えるとは限りません。ツールが利用可能だと決めつけるのではなく、機能の有無を検出してください。
6. アダプターレイヤーをバージョン管理する — プラットフォームのスキル読み込みメカニズムの進化に合わせて、アダプターの更新が必要になります。スキルの内容とは独立してバージョン管理してください。
7. 代替手段の指示を用意する — プラットフォームがある機能をネイティブにサポートしていない場合は、ユーザーが実行できる手動の手順を提示してください。

プラットフォーム互換性

機能	Claude Code	Cursor	Codex	Gemini CLI
SKILL.md の読み込み	✅ CLAUDE.md 経由	✅ ネイティブ	⚠️ 指示経由	⚠️ システムプロンプト経由
自動インストール	✅ フック	✅ スキル	✅ CLI	✅ 設定
クロスプラットフォーム CI	✅ 完全対応	✅ 完全対応	✅ 完全対応	✅ 完全対応
アダプターレイヤー	✅ 完全対応	✅ 完全対応	✅ 完全対応	✅ 完全対応
ホットリロード	✅ ファイル監視	✅ ネイティブ	❌ 再起動が必要	❌ 再起動が必要

関連スキル

• プロンプトアーキテクチャ - ハーネス固有のローダーが適応する、移植可能なコアを構成するプラットフォームに依存しないプロンプトのレイヤリング
• Anthropic ツールの習熟 - プラットフォーム固有のツールインターフェースに合わせて適応する必要がある、ツールオーケストレーションのパターン
• コンテキストエンジニアリング - あらゆる環境に適用できる一方、トークン予算の調整にはプラットフォーム固有の対応が必要なコンテキスト管理の手法

キーワード

マルチハーネス、移植性、クロスプラットフォーム、一度書けばどこでも実行、プラットフォームアダプター、スキルのインストール、claude-code、cursor、codex、gemini、エージェントスキル

---

© 2026 googleadsagent.ai™ | Agent Skills™ | MIT License