Cross-Provider Portability — One Harness, Many Agents

You're using Kiro, Claude Code, and Codex. Tomorrow you might add Gemini CLI or open a file in Cursor. The three-layer architecture (Hooks → Commands → Skills) doesn't belong to any single tool — it's a pattern that maps across all of them.

This lesson shows how the SAW harness implements the same workflow patterns for four different AI coding tools — and how you can make your own harness portable.

The Portability Problem

Every AI coding agent has the same three concepts:

1. Hooks — automatic guardrails that fire on events
2. Commands — user-invoked workflow steps
3. Skills — domain expertise the model loads contextually

But they all use different config formats, different directory conventions, and different invocation syntax. If you build your workflow for one tool, switching costs you a rewrite — unless you design for portability from the start.

The SAW harness solves this by maintaining parallel provider directories with the same logical content adapted to each tool's native format. Your workflows stay the same; only the encoding changes.

How SAW Maps the Three Layers Across Providers

The Full Comparison

Command Syntax Differences

The same workflow action has different invocation syntax per provider:

Gemini CLI uses namespaced commands (/namespace:command) while Claude Code uses flat names (/command). Codex doesn't have slash commands at all — you describe what you want in natural language and it discovers the right skill.

The Shared .agents/skills/ Directory

The directory contains 18 skills covering patterns like:

• api-patterns/ — API design conventions
• safe-workflow/ — SAFe methodology gates and exit states
• pattern-discovery/ — "Search first, reuse always, create only when necessary"
• orchestration-patterns/ — multi-agent coordination

Each provider-specific directory (.claude/skills/, .gemini/skills/) adapts these for its native format. The shared directory is the source of truth.

Hook Mechanisms Compared

Claude Code: hooks-config.json

Declarative JSON. Hooks fire on lifecycle events (PreToolUse, PostToolUse, etc.) and can block actions.

{
  "hooks": {
    "PreCommit": [
      {
        "command": "bash scripts/pre-commit-check.sh",
        "blocking": true
      }
    ]
  }
}

Gemini CLI: settings.json hooks section

Similar lifecycle model but lives inside the broader settings file alongside model config and MCP servers.

{
  "hooks": {
    "pre_commit": {
      "command": "bash scripts/pre-commit-check.sh",
      "blocking": true
    }
  },
  "model": "gemini-3-flash",
  "mcpServers": { ... }
}

Gemini also offers a dedicated migration command: gemini hooks migrate --from-claude to translate Claude's hooks-config.json into its own format.

Codex CLI: config.toml approval policy

Codex takes a different approach. Instead of event-based hooks, it uses an approval policy that controls what the agent can do without asking:

[approval]
# "suggest" = always ask, "auto-edit" = allow file edits, "full-auto" = allow everything
mode = "auto-edit"

[sandbox]
enabled = true
network = false

The sandbox and approval modes serve the same purpose as hooks — constraining agent behavior — but expressed as a policy rather than event listeners.

Cursor IDE: Glob-Activated Rules

Cursor uses .mdc files with YAML frontmatter that activates rules based on file patterns:

---
description: Enforce commit message format
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: true
---

# Git Commit Rules
All commits must reference a ticket number...

Rules numbered 00-02 are "always apply" (equivalent to hooks). Higher numbers activate contextually.

Migration Path: Adding Claude Code to Your Kiro Harness

Your ~/Developer/agent-workflow/ is currently Kiro-only. Adding Claude Code support means creating a .claude/ directory alongside your existing .kiro/. Here's what that looks like:

The migration steps:

1. Map your steering files to skills. Kiro steering files (always-included markdown with frontmatter) become Claude Code skills with Skills 2.0 frontmatter triggers.
2. Create hooks-config.json. Any constraints in your Kiro setup that should be enforced (not just suggested) become hooks.
3. Encode repeatable workflows as commands. Any multi-step process you find yourself explaining to Kiro repeatedly becomes a .claude/commands/*.md file.
4. Extract shared skills to .agents/skills/. Skills that aren't provider-specific go in the shared directory so Codex (and future tools) can discover them too.

Key Takeaways

• The three-layer pattern (Hooks → Commands → Skills) is provider-agnostic. Every tool implements it differently, but the concepts are the same.
• SAW maintains parallel provider directories (.claude/, .gemini/, .codex/, .cursor/) with equivalent content in each tool's native format.
• The .agents/skills/ directory is the cross-provider source of truth for domain expertise.
• Adding a new provider doesn't require rewriting — it requires translating your existing patterns into the new format.
• Gemini uses namespaced commands (/workflow:start-work), Claude uses flat names (/start-work), Codex uses natural language, and Cursor uses @rule invocations.

Check Your Understanding

What's Next

You now understand how to structure your agent harness for portability across providers. The next lesson covers harness sync and versioning — how to keep your local harness up-to-date with upstream changes without losing your customizations.