multi-harness-portability

多 Harness 可移植性

Agent Skills™ 的一部分，出自 googleadsagent.ai™

描述

多 Harness 可移植性是一门工程学科，旨在编写能够在所有主流 AI 编码 Harness 中运行的 Agent 技能、提示词和配置，包括 Claude Code、Cursor、Codex、Gemini CLI、OpenCode 等。AI 工具领域正在迅速分化：不同团队使用不同的编辑器、不同的 CLI 工具和不同的模型。被锁定在单一平台上的技能会成为负担；可移植的技能则会成为资产，在整个组织中不断增值。

这项技能包含了为 Agent Skills™ 制定的可移植性架构，该项目由 googleadsagent.ai™ 创建，仓库中的每项技能都旨在适用于所有主流 Harness。关键在于，可移植性是架构层面的决策，而非事后补救。它需要抽象层，将特定于平台的功能（钩子、规则、指令、系统提示词）映射到通用的技能接口，并由特定于平台的适配器负责转换。

可移植性层处理三类平台差异：技能加载（技能如何进入 Agent 的上下文）、工具访问（有哪些工具可用，以及如何调用它们）和输出格式（Agent 如何交付结果）。每一类差异都需要各自的适配器模式，组合起来即可实现真正的一次编写、随处运行的 Agent 技能。

适用场景

• 团队使用多种 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）与特定平台的加载机制之间。平台检测器会识别当前的执行环境。平台适配器会将通用技能格式转换为各个 Harness 的原生配置：Claude Code 使用 CLAUDE.md 和钩子，Cursor 使用 .cursor/rules/ 和 SKILL.md 文件，Codex 使用指令文件，Gemini 使用系统提示词配置。统一执行层可确保无论采用哪种加载路径，Agent 接收到的指令和约束都相同。

实现

平台检测：

#!/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. 至少在两个平台上测试 — 只有在多个平台上实际运行技能，才能发现可移植性问题；CI 验证至关重要。
3. 使用 SKILL.md 格式作为通用源格式 — 这是支持最广泛的格式；所有其他格式都由此衍生。
4. 记录特定于平台的限制 — 如果某项功能需要钩子（仅限 Claude Code）或扩展（仅限 Cursor），请在兼容性表中明确说明。
5. 避免依赖特定工具的假设 — 并非所有平台都提供相同的工具；应使用功能检测，而不是假设工具可用。
6. 为适配器层进行版本管理 — 随着平台不断演进技能加载机制，适配器也需要更新；应独立于技能内容对其进行版本管理。
7. 提供备用指令 — 如果某个平台不原生支持某项功能，请提供用户可以手动执行的指令。

平台兼容性

功能	Claude Code	Cursor	Codex	Gemini CLI
SKILL.md 加载	✅ 通过 CLAUDE.md	✅ 原生支持	⚠️ 通过指令	⚠️ 通过系统提示词
自动安装	✅ Hooks	✅ Skills	✅ CLI	✅ Config
跨平台 CI	✅ 完整支持	✅ 完整支持	✅ 完整支持	✅ 完整支持
适配层	✅ 完整支持	✅ 完整支持	✅ 完整支持	✅ 完整支持
热重载	✅ 文件监视	✅ 原生支持	❌ 需要重启	❌ 需要重启

相关技能

• 提示词架构 - 与平台无关的提示词分层，构成可移植核心，并由针对不同运行环境的加载器进行适配
• Anthropic 工具精通 - 工具编排模式，需针对不同平台的工具接口进行适配
• 上下文工程 - 普遍适用的上下文管理技巧，但需要针对不同平台调整令牌预算

关键词

多运行环境、可移植性、跨平台、一次编写，到处运行、平台适配器、技能安装、claude-code、cursor、codex、gemini、agent-skills

---

© 2026 googleadsagent.ai™ | Agent Skills™ | MIT 许可证