Authoring a profile

1. Sort every file first

This is the judgment the CLI can't make for you — decide it once, at the door.

The file is	Declare as	Lands as
a capability invoked by name	skills: (path must end in SKILL.md)	.claude/skills/<name>/SKILL.md, .agents/skills/…
a named sub-agent persona	agents:	platform-specific agent file
guidance auto-applied to globs	rules:	Cursor .cursor/rules/, converted elsewhere
a slash-command snippet	commands:	/name
MCP server config	mcp: (one mcp.jsonc)	platform MCP config
a script on a tool event	hooks:	translated per platform
the operating manual, or any bundled asset	references: + a role binding	root AGENTS.md section / co-install

forgecat init scaffolds every kind above except references and instructions — they aren't in the template. That's the most common way an operating manual ends up mis-declared as a rule.

2. Operating instructions take two lines, not one

references:
  - id: agents-md
    path: AGENTS.md
    type: operating-instructions
instructions:
  operatingRef: agents-md

Dropping an AGENTS.md in the repo root does nothing by itself — scan calls it type: other, trackable: false, and plan installs zero files. The declaration is what counts, not the filename.

Role-typed references must be bound or install rejects them as inert: persona→personaRef, identity→identityRef, operating-instructions→operatingRef, tool-conventions→additionalRefs.

Only operating reaches every platform. persona / identity / tool-conventions are written to files on home-target platforms only (OpenClaw, Hermes); on Claude Code, Cursor and Codex they co-install as assets and nothing more. If the content must reach every user, it goes in operating.

3. Keep companion files with the skill

A skill can include companion files under its directory, such as references/ and scripts/. Standard installation preserves their relative paths alongside SKILL.md. Declare executable scripts in skills[].scripts.

Profile-level references declared separately in profile.yml are co-installed under .forgecat/profiles/@scope/name/. Use a declared reference token to reach those assets.

Check relative links against the installed layout. Links to sibling skills or project-root files need separate verification.

4. The loop

forgecat init .     # scaffold
forgecat scan       # find files on disk that aren't declared
forgecat track      # add them interactively
forgecat validate   # schema, names, paths, hooks — no network
forgecat plan       # what lands where, per platform — no writes

When scan and plan disagree, plan wins. scan guesses from files on disk; plan reads declarations. A scan warning that a reference "will be dropped at install" is often a false alarm — read plan before changing anything.

But plan shows where declared resources land, not everything install does. It won't mention the CLAUDE.md import shim or co-installed reference assets, so the file count after install can exceed the plan. plan is authoritative about placement, not about the total.

You can't test-install from a local path (Only registry sources are supported). validate + plan is as far as verification goes before you publish.

Verify

forgecat validate && forgecat plan

🐾✓ when both come back clean.