File Placement

How agex decides where to write artifact files based on your tools and artifact type.

When you run agex sync or agex add, the CLI materializes artifacts into the correct locations for each tool declared in your agex.toml. This is handled automatically — you don't need to know where each file goes.

How placement works

The CLI looks at:

The tools array in your [project] section
The artifact type (claude-md, mcp-server, hook, etc.)

For each tool that supports that artifact type, a target file path and write strategy are determined.

Placement rules by platform

Claude Code

Artifact type	File path	Strategy
`claude-md`	`CLAUDE.md`	replace
`agents-md`	`AGENTS.md`	replace
`skill-*`	`.claude/skills/{name}/SKILL.md`	replace
`hook` / `hook-config`	`.claude/settings.local.json`	merge-json (`hooks`)
`mcp-config` / `mcp-server`	`.mcp.json`	merge-json (`mcpServers`)
`subagent` / `agent-team` / `agent-prompt`	`.claude/agents/{name}.md`	replace
`command` / `slash-command`	`.claude/commands/{name}.md`	replace

Cursor

Artifact type	File path	Strategy
`cursorrules`	`.cursorrules`	replace
`skill-*`	`.cursor/rules/{name}.mdc`	replace
`mcp-config` / `mcp-server`	`.cursor/mcp.json`	merge-json (`mcpServers`)
`hook` / `hook-config`	`.cursor/hooks.json`	merge-json (`hooks`)
`subagent` / `agent-prompt`	`.cursor/agents/{name}.md`	replace

Gemini CLI

Artifact type	File path	Strategy
`gemini-md`	`GEMINI.md`	replace
`agents-md`	`AGENTS.md`	replace
`skill-*`	`.gemini/skills/{name}/SKILL.md`	replace
`mcp-config` / `mcp-server`	`.gemini/settings.json`	merge-json (`mcpServers`)
`hook` / `hook-config`	`.gemini/settings.json`	merge-json (`hooks`)
`subagent`	`.gemini/agents/{name}.md`	replace

OpenCode

Artifact type	File path	Strategy
`agents-md`	`AGENTS.md`	replace
`skill-*`	`.opencode/skills/{name}/SKILL.md`	replace
`mcp-config` / `mcp-server`	`.opencode/settings.json`	merge-json (`mcpServers`)
`hook`	`.opencode/settings.json`	merge-json (`hooks`)
`subagent`	`.opencode/agents/{name}.md`	replace
`command`	`.opencode/commands/{name}.md`	replace

Codex

Artifact type	File path	Strategy
`agents-md`	`AGENTS.md`	replace
`skill-*`	`.codex/skills/{name}/SKILL.md`	replace
`mcp-config` / `mcp-server`	`.mcp.json`	merge-json (`mcpServers`)
`subagent` / `agent-prompt`	`.codex/agents/{name}.md`	replace

Write strategies

`replace`

The artifact content is written directly to the target path, overwriting whatever was there. Used for single-file artifacts like CLAUDE.md and agent definitions.

`merge-json`

Used for shared JSON config files (.mcp.json, .claude/settings.local.json). The artifact must contain a JSON block. The CLI:

Parses the artifact's JSON content (either raw JSON or a fenced ```json ``` block)
Reads the existing file (or starts with {} if it doesn't exist)
Merges the artifact's entries under the appropriate key (mcpServers, hooks, etc.)
Tags each merged entry with _agex_ref so it can be cleanly removed later

This means multiple MCP server artifacts can coexist in the same .mcp.json without conflicts.

Remote vs. local artifacts

Remote artifacts (from the hub) of types that normally write to a shared file (CLAUDE.md, .cursorrules, AGENTS.md) are redirected to a namespaced location to avoid overwriting your own config:

Platform	Remote artifact location
Claude Code	`.claude/rules/{artifact-slug}.md`
Cursor	`.cursor/rules/{artifact-slug}.mdc`
Others	`.agex/artifacts/{type}/{artifact-slug}.md`

Local artifacts (declared with local: prefix) write directly to the shared file, since they are your config.

Fallback

If no placement rule matches a given tool + artifact type combination, the artifact is written to:

.agex/artifacts/{type}/{name}.md

`{name}` substitution

Paths containing {name} use the manifest key (the left side of the = in agex.toml) as the file name. For example:

[skills]
deploy-recipe = "@rkrebs/vercel-deploy"

With Claude Code, this writes to .claude/skills/deploy-recipe/SKILL.md.

On this page