Migrating from OAC to Claude Code

Convert OpenAgents Control agents to Claude Code's .claude/ directory format

Overview

Export to Claude Code format when you want to use your agents with Claude Code IDE. Claude Code supports subagents (.claude/agents/*.md), Skills (.claude/skills/), and hooks, making it a feature-rich target with good OAC compatibility.

Prerequisites

Requirement	Version	Notes
Node.js	>= 18	Required for CLI
@openagents-control/compatibility-layer	Latest	Install via npm
Claude Code	Any	Target platform

npm install -g @openagents-control/compatibility-layer

Quick Migration

# Single agent conversion
oac-compat convert agent.md -f claude -o .claude/

# Convert with verbose output
oac-compat convert agent.md -f claude -o .claude/ --verbose

# Validate before converting
oac-compat validate --target claude agent.md

Step-by-Step Manual Migration

1. OAC Agent Structure

Typical OAC agent with full features:

---
name: DocWriter
description: Documentation authoring agent
mode: subagent
temperature: 0.2
model: claude-sonnet-4
tools:
  read: true
  write: true
  edit: true
  bash: false
permission:
  bash:
    "*": "deny"
  edit:
    "**/*.md": "allow"
    "**/*.env*": "deny"
skills:
  - context-manager
  - task-management
hooks:
  - event: PreToolUse
    matchers: ["edit"]
    commands:
      - type: command
        command: "echo 'Editing file...'"
maxSteps: 50
---

# DocWriter

> Mission: Create and update documentation

## Rules

1. Always follow project documentation standards
2. Use concise, example-driven writing
3. Propose changes before implementing

2. Claude Code Structure

Equivalent .claude/agents/DocWriter.md format:

---
name: "DocWriter"
description: "Documentation authoring agent"
tools: "Read, Write, Edit"
model: "claude-sonnet-4-20250514"
permissionMode: "default"
skills: ["context-manager", "task-management"]
hooks: {"PreToolUse": [{"matcher": "edit", "hooks": [{"type": "command", "command": "echo 'Editing file...'"}]}]}
---

# DocWriter

> Mission: Create and update documentation

## Rules

1. Always follow project documentation standards
2. Use concise, example-driven writing
3. Propose changes before implementing

3. Key Differences

Aspect	OAC	Claude Code
File format	Markdown + YAML frontmatter	Markdown + YAML frontmatter
File location	`.opencode/agent/*.md`	`.claude/agents/*.md` (subagents) or `.claude/config.json` (primary)
Multiple agents	Supported	Supported (as subagents)
Permissions	Granular (allow/deny/ask per path)	Binary (permissionMode)
Skills	Full system	Supported (`.claude/skills/`)
Hooks	Full system	Supported (PreToolUse, PostToolUse, etc.)
Contexts	Referenced files	Converted to Skills
Temperature	Supported	Not supported
maxSteps	Supported	Not supported

4. Feature Mapping

OAC Feature	Claude Code Equivalent	Notes
`frontmatter.name`	`name` in frontmatter	Direct mapping
`frontmatter.description`	`description` in frontmatter	Direct mapping
`frontmatter.model`	`model` in frontmatter	Model name converted
`frontmatter.temperature`	N/A	Not supported - warning emitted
`frontmatter.mode`	File location	`primary` → `config.json`, `subagent` → `agents/*.md`
`frontmatter.tools`	`tools` in frontmatter	Converted to comma-separated string
`frontmatter.permission`	`permissionMode`	Degraded to binary mode
`frontmatter.skills`	`skills` array	Direct mapping
`frontmatter.hooks`	`hooks` object	Converted to Claude format
`frontmatter.maxSteps`	N/A	Not supported - warning emitted
`contexts`	`.claude/skills/`	Converted to skill files
`systemPrompt`	Body content	Direct mapping

5. Model Name Mapping

OAC Model	Claude Code Model
`claude-sonnet-4`	`claude-sonnet-4-20250514`
`claude-opus-4`	`claude-opus-4`
`claude-haiku-4`	`claude-haiku-4`
Other models	`sonnet` (default alias)

Common Patterns

Pattern 1: Basic Subagent

Before (OAC):

---
name: CodeReviewer
description: Reviews code for quality
mode: subagent
tools:
  read: true
  grep: true
  glob: true
---

# Code Reviewer

Review code for:
- Code style consistency
- Potential bugs
- Performance issues

After (Claude Code .claude/agents/CodeReviewer.md):

---
name: "CodeReviewer"
description: "Reviews code for quality"
tools: "Read, Grep, Glob"
---

# Code Reviewer

Review code for:
- Code style consistency
- Potential bugs
- Performance issues

Pattern 2: Primary Agent with Hooks

Before (OAC):

---
name: MainAgent
description: Primary development agent
mode: primary
model: claude-opus-4
hooks:
  - event: PreToolUse
    matchers: ["bash"]
    commands:
      - type: command
        command: "echo 'Running bash command...'"
  - event: PostToolUse
    matchers: ["write"]
    commands:
      - type: command
        command: "npm run lint"
---

# Main Agent

Primary agent for development tasks.

After (Claude Code .claude/config.json):

{
  "name": "MainAgent",
  "description": "Primary development agent",
  "systemPrompt": "# Main Agent\n\nPrimary agent for development tasks.",
  "model": "claude-opus-4",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          { "type": "command", "command": "echo 'Running bash command...'" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "write",
        "hooks": [
          { "type": "command", "command": "npm run lint" }
        ]
      }
    ]
  }
}

Pattern 3: Agent with Contexts (→ Skills)

Before (OAC):

---
name: StyleGuide
description: Enforces code style
mode: subagent
---

# Style Guide Agent

Follow the project style guide.

With contexts:

[
  { "path": ".opencode/context/style-guide.md", "priority": "critical", "description": "Project style guidelines" }
]

After (Claude Code):

.claude/agents/StyleGuide.md:

---
name: "StyleGuide"
description: "Enforces code style"
skills: ["style-guide"]
---

# Style Guide Agent

Follow the project style guide.

.claude/skills/style-guide/SKILL.md:

---
name: style-guide
description: Project style guidelines
---

# style-guide

This skill provides context from: `.opencode/context/style-guide.md`

Priority: critical

Load the full context file for detailed information:
```bash
cat .opencode/context/style-guide.md


### Pattern 4: Agent with Granular Permissions

**Before (OAC):**

```yaml
---
name: SecureWriter
description: Writes files with restrictions
mode: subagent
permission:
  edit:
    "src/**/*.ts": "allow"
    "**/*.env*": "deny"
  bash:
    "*": "deny"
---

# Secure Writer

Write TypeScript files only. Never access secrets.

After (Claude Code .claude/agents/SecureWriter.md):

---
name: "SecureWriter"
description: "Writes files with restrictions"
permissionMode: "default"
---

# Secure Writer

Write TypeScript files only. Never access secrets.

## Permission Notes

> **Warning**: Granular OAC permissions were degraded to `permissionMode: default`.
> Original restrictions:
> - edit: Only `src/**/*.ts` allowed
> - edit: `**/*.env*` denied
> - bash: Completely denied
>
> Enforce these manually.

Limitations

Features Lost in Conversion

Feature	Impact	Workaround
temperature	Not supported	Use creativity settings in Claude Code
maxSteps	Not supported	Claude Code manages internally
Granular permissions	Degraded to `permissionMode`	Document restrictions in prompt

Permission Mode Mapping

OAC Permission Pattern	Claude `permissionMode`
All `"allow"` / `true`	`bypassPermissions`
All `"deny"` / `false`	`dontAsk`
Contains `"ask"`	`default`
Mixed/complex rules	`default` (with warning)

Conversion Warnings

The converter emits warnings for:

⚠️  Agent name is required for Claude Code
⚠️  Agent description is required for Claude Code
⚠️  temperature not supported in Claude Code (value: 0.2)
⚠️  maxSteps not supported in Claude Code (value: 50)
⚠️  granular permissions degraded: allow/deny/ask per operation → binary permissionMode (default/acceptEdits/dontAsk/bypassPermissions)
⚠️  Complex permission rules degraded to 'default' permissionMode. Claude Code does not support granular allow/deny/ask per operation.

What's Preserved

Agent name and description
Model selection (with name mapping)
System prompt content
Tool access list
Skills references
Hooks (full conversion)
Contexts (converted to Skills)

Validation

Verify Conversion Success

# 1. Run conversion with verbose output
oac-compat convert agent.md -f claude -o .claude/ --verbose

# 2. Check for warnings
# Review any warnings about degraded features

# 3. Validate output files exist
ls -la .claude/
ls -la .claude/agents/
ls -la .claude/skills/

# 4. Test in Claude Code
# Open project in Claude Code and verify agent behavior

Manual Verification Checklist

.claude/config.json created (for primary agents)
.claude/agents/*.md created (for subagents)
.claude/skills/ created (if contexts present)
Agent name and description present in frontmatter
Model setting correct (with Claude naming)
System prompt content complete
Tools list includes expected tools
Skills references match generated skill files
Hooks converted correctly (if applicable)
Warnings reviewed and addressed

Programmatic Validation

import { ClaudeAdapter, loadAgent } from '@openagents-control/compatibility-layer';

async function validateConversion() {
  const agent = await loadAgent('./agent.md');
  const adapter = new ClaudeAdapter();
  
  // Check capabilities
  const caps = adapter.getCapabilities();
  console.log('Claude Code capabilities:', caps);
  // Output: { supportsSkills: true, supportsHooks: true, supportsTemperature: false, ... }
  
  // Validate conversion
  const warnings = adapter.validateConversion(agent);
  if (warnings.length > 0) {
    console.log('Conversion warnings:', warnings);
  }
  
  // Convert
  const result = await adapter.fromOAC(agent);
  
  if (result.success) {
    console.log('Conversion successful!');
    console.log('Output files:', result.configs.map(c => c.fileName));
    // Output: ['.claude/agents/MyAgent.md', '.claude/skills/context-skill/SKILL.md']
    console.log('Warnings:', result.warnings);
  } else {
    console.error('Conversion failed:', result.errors);
  }
}

Troubleshooting

Common Issues

"Agent name is required" warning

Cause: OAC agent doesn't have a name in frontmatter.

Solution: Add name to your OAC agent:

---
name: MyAgent
description: My agent description
---

Temperature setting ignored

Cause: Claude Code doesn't support temperature control.

Solution: No direct equivalent. Claude Code manages creativity internally. Remove temperature from your expectations or use Claude Code's built-in settings.

maxSteps not available

Cause: Claude Code doesn't expose step limits.

Solution: No workaround - Claude Code manages execution internally.

Permissions not enforced granularly

Cause: Claude Code only supports permissionMode (binary modes).

Solution: Document permission restrictions in your system prompt:

# IMPORTANT RESTRICTIONS
- Only edit files in src/ directory
- Never access .env files
- Do not run bash commands without approval

Or accept the degraded permissionMode:

default - Prompts for permission
acceptEdits - Auto-accepts edits
dontAsk - Auto-denies
bypassPermissions - Full access

Skills not loading in Claude Code

Cause: Skills must be in .claude/skills/{name}/SKILL.md format.

Solution: Verify the skill directory structure:

.claude/
  skills/
    my-skill/
      SKILL.md    # Must be named SKILL.md

Hooks not triggering

Cause: Hook format mismatch or unsupported event.

Solution: Verify hooks use supported events:

PreToolUse - Before tool execution
PostToolUse - After tool execution
PermissionRequest - On permission prompt
AgentStart - Agent session start
AgentEnd - Agent session end

Check hook format in converted file:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [{ "type": "command", "command": "echo 'test'" }]
      }
    ]
  }
}

Next Steps

Claude → OAC Migration - Import Claude Code configurations
OAC → Cursor Migration - Convert to Cursor format
Feature Capabilities Matrix - Full feature comparison
Claude Code Documentation - Official Claude Code docs

oac-to-claude.md 13 KB History Raw

Migrating from OAC to Claude Code

Overview

Prerequisites

Quick Migration

Step-by-Step Manual Migration

1. OAC Agent Structure

2. Claude Code Structure

3. Key Differences

4. Feature Mapping

5. Model Name Mapping

Common Patterns

Pattern 1: Basic Subagent

Pattern 2: Primary Agent with Hooks

Pattern 3: Agent with Contexts (→ Skills)

Limitations

Features Lost in Conversion

Permission Mode Mapping

Conversion Warnings

What's Preserved

Validation

Verify Conversion Success

Manual Verification Checklist

Programmatic Validation

Troubleshooting

Common Issues

"Agent name is required" warning

Temperature setting ignored

maxSteps not available

Permissions not enforced granularly

Skills not loading in Claude Code

Hooks not triggering

Next Steps

oac-to-claude.md 13 KB

History Raw