A good profile has one job. It might review pull requests, run a sales workflow, or carry your team's development conventions. Keep the files needed for that job together, follow ForgeCat's resource directories, and describe the profile in profile.yml. ForgeCat can then install it in the format each supported tool expects.

Start small

You do not need every resource type in every profile. An engineering review profile could begin with one agent, one skill, and a shared operating guide:

review-profile/
├── profile.yml
├── README.md
├── AGENTS.md
├── agents/
│   └── reviewer.md
└── skills/
    └── review/
        └── SKILL.md

Add rules, commands, hooks, or MCP servers only when the profile's purpose calls for them.

Use the resource directories

For agents, skills, rules, and commands, the first directory in a source path determines the resource type during installation:

The manifest does not override this path-based classification. For example, agents/reviewer.md is handled as an agent even if it was left out of agents[], while a declared subagents/reviewer.md is not. Keep resources under the expected top-level directory, then declare them in profile.yml so ForgeCat can validate and describe the profile consistently.

MCP configuration is detected from mcp.path or a recognized MCP filename. Hooks and references rely on their manifest declarations.

Describe the profile in profile.yml

name: "@creator/review-profile"
description: Review pull requests for correctness, security, and maintainability.
visibility: public

agents:
  - name: reviewer
    path: agents/reviewer.md
    description: Reviews a change and reports concrete findings.
    model: inherit
    tools: [read, grep]

skills:
  - name: review
    path: skills/review/SKILL.md
    description: A repeatable code-review workflow.

references:
  - id: operating
    path: AGENTS.md

instructions:
  operatingRef: operating

Put portable metadata such as an agent's name, description, model, and tools in profile.yml. Keep the agent's actual instructions in its Markdown file. During install, ForgeCat combines the manifest metadata with that body and writes the native format for the selected platform.

Skill metadata works the same way. If SKILL.md already has name or description frontmatter, ForgeCat keeps those values. Otherwise it fills them from the matching skills[] entry.

Because files under a recognized resource directory can still ship when they are undeclared, run forgecat scan before publishing. It catches resources that are present on disk but missing from the manifest.

Only add compatibility.platforms.tested or partial after you have tried the profile on those platforms. Compatibility is a record of what you verified, not an install switch.

What can a profile contain?

Use {{ref:<id>}} in an agent, skill, rule, command, MCP config, or hook script when it needs the installed path of a supporting reference. The token resolves only for references that ForgeCat co-installs as assets. A token pointing to operating instructions stays unchanged because that document goes directly to AGENTS.md or SOUL.md instead.

agents/*.md and AGENTS.md are different

The similar names hide two separate flows:

• agents/reviewer.md defines a subagent. Declare it in agents[] and ForgeCat converts it to the selected platform's agent format.
• Root AGENTS.md contains what ForgeCat calls operating instructions: guidance loaded by the main agent for every session. Its filename alone does nothing. Declare it as a reference and bind it with instructions.operatingRef, as in the example above.

This distinction matters because the files land in different places. Subagents go into a platform-specific agents directory. Operating guidance joins the bootstrap instructions that the main agent reads every session.

On Claude Code, Codex, Cursor, and OpenClaw, operating instructions land in a managed section of AGENTS.md. Claude Code reaches that file through an @AGENTS.md import in CLAUDE.md. Hermes Agent receives the same operating instructions in a managed SOUL.md section.

Platform support at a glance

Here, operating instructions is the cross-platform name for always-loaded guidance exposed through CLAUDE.md, AGENTS.md, or SOUL.md. The section above explains where ForgeCat stores it on each platform.

A checkmark means ForgeCat supports that resource on the platform. A muted dot means it is not supported and ForgeCat skips it. Follow the target guide for exact paths, conversions, and platform-specific limitations.

Choose the target guide

ForgeCat supports two kinds of agent environment, and they do not expose the same features:

• Claude Code, Codex, and Cursor keep configuration inside a project. They support agents, skills, rules, commands, hooks, and MCP connections, with a few platform-specific differences.
• OpenClaw and Hermes Agent load skills and instructions from an agent workspace or profile home. They do not have equivalent drop-in files for every project resource.

Check before you publish

forgecat scan
forgecat validate --strict
forgecat plan
forgecat push --dry-run

forgecat scan finds resources you have not declared. validate checks the manifest and referenced files. plan shows where each resource will land without writing anything.