Claude Code, Codex, and Cursor keep agent configuration inside the project. ForgeCat starts from the same profile.yml and source files, then writes the native layout for whichever platforms you install into.

Where resources land

All paths below are relative to the project root.

What ForgeCat converts

Agents

The Markdown body becomes the agent's instructions. ForgeCat takes portable metadata from the matching agents[] entry and writes the fields supported by each platform:

• Claude Code and Cursor receive Markdown agents with native frontmatter.
• Codex receives a TOML agent with the Markdown body as developer instructions.
• Skills declared in the same profile are installed alongside the agents. Claude Code also receives the skill paths in generated agent metadata; Codex and Cursor discover them from their skill directories.

Keep platform-independent metadata in profile.yml so one source can produce all three formats.

Skills

Skills keep their directory structure and content. ForgeCat only fills missing name and description frontmatter in SKILL.md. A skill therefore remains readable and editable as a standard Agent Skills package after installation.

Platform skill directories are not namespaced by profile. If two profiles contain a skill with the same directory name but different content, ForgeCat asks before replacing it. The lockfile tracks shared ownership so uninstalling one profile does not remove a skill another installed profile still uses.

Rules and commands

Claude Code rules remain Markdown, with globs mapped to paths. Commands go to .claude/commands/, and ForgeCat strips their source frontmatter during conversion. Cursor rules and commands become .mdc files.

Codex has no standalone command target. Rules join the project root AGENTS.md as profile-owned sections instead.

Codex rule section names have two restrictions. Do not use the root path rules/operating-instructions.md, which is reserved for instructions.operatingRef, or put : anywhere in a rule path. ForgeCat stops the install with an error in either case because the path cannot be represented safely in its AGENTS.md section markers.

MCP and hooks

ForgeCat converts JSONC MCP configuration to JSON for Claude Code and Cursor, and to TOML for Codex. It merges the result into the existing config instead of replacing the file.

Standard hook triggers and supported tool matchers are translated into each platform's names. If a tool matcher has no equivalent on the target platform, ForgeCat skips that hook and reports why. Hook scripts are installed with the profile and run through ForgeCat's input-normalization wrapper. Codex users still need to review and trust installed hooks with /hooks before they run.

How operating instructions are shared

Operating instructions are the profile's always-loaded guidance. Binding a reference with instructions.operatingRef adds that document to the project root AGENTS.md:

references:
  - id: operating
    path: AGENTS.md

instructions:
  operatingRef: operating

ForgeCat wraps the content in profile-specific markers. Existing project guidance stays untouched, and several profiles can contribute separate sections to the same file. Updating a profile replaces only its section; uninstalling it removes only that section.

Claude Code loads CLAUDE.md, so ForgeCat also makes sure CLAUDE.md imports @AGENTS.md once. The operating instructions themselves still live in one place.

Bring native files when conversion is not enough

Most profiles should use standard conversion. If one platform needs configuration that the portable manifest cannot express, set that platform to override:

platforms:
  codex:
    mode: override

Place ready-to-install files under platforms/codex/. ForgeCat removes that prefix and copies the remaining tree as-is. Cursor and Claude Code still use standard conversion unless they have their own override.

Run forgecat plan before publishing to compare all three outputs.