Multi Harness Portability

# Multi-Harness Portability

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

## Description

Multi-Harness Portability is the engineering discipline of writing agent skills, prompts, and configurations that work across every major AI coding harness — Claude Code, Cursor, Codex, Gemini CLI, OpenCode, and beyond. The AI tooling landscape is fragmenting rapidly: teams use different editors, different CLI tools, different models. Skills that are locked to a single platform become liabilities; skills that are portable become assets that compound in value across the entire organization.

This skill encodes the portability architecture developed for [Agent Skills™](https://github.com/itallstartedwithaidea/agent-skills) by [googleadsagent.ai™](https://googleadsagent.ai), where every skill in the repository is designed to function across all major harnesses. The key insight is that portability is an architectural decision, not an afterthought. It requires abstraction layers that map platform-specific capabilities (hooks, rules, instructions, system prompts) to a universal skill interface, with platform-specific adapters handling the translation.

The portability layer handles three categories of platform differences: skill loading (how the skill enters the agent's context), tool access (what tools are available and how they're invoked), and output formatting (how the agent delivers results). Each category requires its own adapter pattern, and the combination provides true write-once-run-anywhere agent skills.

## Use When

- Your team uses multiple AI coding tools (Claude Code, Cursor, Codex, etc.)
- You want to maintain a single skill repository that serves all platforms
- Skills developed for one platform need to be ported to others
- You are building an open-source skill library for the community
- CI/CD pipelines need to validate skills across multiple platforms
- Organization policy requires platform-agnostic tooling

## How It Works

```mermaid
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
```

The portability layer sits between the universal skill definition (SKILL.md) and the platform-specific loading mechanism. A platform detector identifies the current execution environment. Platform adapters translate the universal skill format into the native configuration of each harness: Claude Code uses CLAUDE.md and hooks, Cursor uses `.cursor/rules/` and SKILL.md files, Codex uses instruction files, and Gemini uses system prompt configuration. The unified execution layer ensures that regardless of the loading path, the agent receives equivalent instructions and constraints.

## Implementation

**Platform Detection:**

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

**Universal Skill Installer:**

```python
import os
import shutil
from pathlib import Path

class SkillInstaller:
    PLATFORM_CONFIGS = {
        "claude-code": {
            "skill_dir": ".",
            "rules