meta-unify-core

Meta-Unify Core Skill

This skill provides the parsing, translation, and generation logic that powers the meta-unify plugin. It is not invoked directly by users but is called by meta-unify commands to perform configuration operations.

Core Capabilities

What This Skill Does

1. Parses Configuration Requests: Interprets natural language or structured requests for adding/modifying MCP servers, skills, hooks, rules, or instructions
2. Translates Between Formats: Converts configuration syntax between Claude Code and Codex formats
3. Generates Configuration Files: Creates or modifies the appropriate files for both systems
4. Validates Output: Ensures generated configurations are syntactically correct before writing

Configuration Types Handled

Type	Description
MCP Servers	Model Context Protocol server definitions (STDIO and HTTP transports)
Skills	Reusable capability bundles with assets, scripts, and references
Hooks	Event-triggered actions (Claude only)
Rules	Permission and constraint definitions
Instructions	System-wide or project-scoped behavioral guidelines
Plugins	Complete Claude Code plugin scaffolding and generation

---

File Location Mappings

Quick Reference Table

Config Type	Claude User Scope	Claude Project Scope	Codex User Scope	Codex Project Scope
MCP servers	~/.claude.json	.mcp.json	~/.codex/config.toml	N/A
Skills	~/.claude/skills/	.claude/skills/	~/.codex/skills/	.codex/skills/
Hooks	~/.claude/settings.json	.claude/settings.json	N/A	N/A
Rules	~/.claude/settings.json (permissions)	.claude/settings.json	~/.codex/rules/*.rules	N/A
Instructions	~/.claude/CLAUDE.md	.claude/CLAUDE.md	~/.codex/AGENTS.md	AGENTS.md

Notes on Scope Differences

• Codex MCP: Only supports user-scope configuration in config.toml
• Codex Hooks: Not supported; use rules for command-level control
• Codex Rules: Starlark-based files in ~/.codex/rules/ directory

---

Format Translation Rules

MCP Servers

Claude (JSON) → Codex (TOML)

// Claude (.mcp.json or ~/.claude.json)
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["@package/server"],
      "env": { "KEY": "value" }
    }
  }
}

# Codex (~/.codex/config.toml)
[mcp_servers.server-name]
command = "npx"
args = ["@package/server"]

[mcp_servers.server-name.env]
KEY = "value"

HTTP Transport

// Claude
{
  "mcpServers": {
    "remote-server": {
      "url": "https://api.example.com/mcp"
    }
  }
}

# Codex
[mcp_servers.remote-server]
url = "https://api.example.com/mcp"

Skills

Both systems use SKILL.md with YAML frontmatter. Key differences:

Property	Claude	Codex
Name	name (max 64 chars)	name (max 100 chars)
Description	description (max 1024 chars)	description (max 500 chars)
User-callable	user-invocable: true/false	Always invocable via $skill-name
Extra fields	allowed-tools, model, context	metadata.short-description

Translation: Claude-specific fields are omitted from Codex version silently.

Permissions / Rules

Claude (settings.json permissions)

{
  "permissions": {
    "allow": ["Bash(npm run:*)"],
    "ask": ["Bash(git push:*)"],
    "deny": ["Bash(rm -rf:*)"]
  }
}

Codex (Starlark .rules file)

prefix_rule(
    pattern = ["npm", "run"],
    decision = "allow",
)

prefix_rule(
    pattern = ["git", "push"],
    decision = "prompt",
)

prefix_rule(
    pattern = ["rm", "-rf"],
    decision = "forbidden",
)

Instructions

Claude (CLAUDE.md) and Codex (AGENTS.md) use the same markdown format.

Special sections:

• ## Claude Only → Only in CLAUDE.md
• ## Codex Only → Only in AGENTS.md

---

Parsing Heuristics

Transport Type Detection

Pattern	Inferred Transport
npx @package/...	STDIO
node script.js	STDIO
python -m module	STDIO
Any executable command	STDIO
https:// or http:// URL	HTTP

Skill Structure Suggestions

Keyword in Request	Suggested Structure
"guidelines", "docs", "reference", "API"	references/ directory
"deploy", "build", "run", "validate"	scripts/ directory
"template", "scaffold", "generate"	assets/ directory

Environment Variable Patterns

Pattern	Action
API_KEY, TOKEN, SECRET	Warn about sensitive data
${VAR} or $VAR	Preserve as env var reference

---

Validation Requirements

Before Writing Configuration

1. JSON Validation (Claude configs)

   • Valid JSON syntax
   • Required keys present
   • Correct structure

2. TOML Validation (Codex configs)

   • Valid TOML syntax
   • Required sections present

3. Starlark Validation (Codex rules)

   • Valid Python-like syntax
   • prefix_rule() calls are correct

4. Command Existence Check (STDIO MCP)

   • Verify command exists in PATH
   • Warn if not found

---

Error Handling

Partial Failure Protocol

When one system succeeds but the other fails:

1. Do NOT roll back the successful write
2. Report clearly which system succeeded and which failed
3. Show the error from the failed system
4. Ask user how to proceed:
   • Keep successful changes
   • Retry failed system
   • Abort and restore

Error Message Format

[meta-unify] ERROR: Failed to write Codex config
  File: ~/.codex/config.toml
  Reason: Invalid TOML syntax - unclosed string at line 15
  Action: Please check the configuration and retry

---

Reference Documentation

For detailed format specifications, see:

• references/claude-formats.md - Complete Claude Code configuration schemas
• references/codex-formats.md - Complete Codex configuration schemas
• references/plugin-formats.md - Claude Code plugin structure and manifest formats

---

Integration Notes

Called By

• /meta-unify:add-mcp - Adding MCP servers
• /meta-unify:add-skill - Creating new skills
• /meta-unify:add-hook - Adding hooks (Claude only)
• /meta-unify:add-rule - Adding permission rules
• /meta-unify:add-plugin - Creating new Claude Code plugins
• /meta-unify:sync - Synchronizing configs between systems

Limitations

• Codex hooks are not supported; suggests rule-based alternatives
• Cannot migrate complex Starlark rules to Claude permissions automatically
• Does not validate MCP server functionality, only syntax