Conversions

The conversions field in agentsmesh.yaml controls how features are projected when a target lacks native support for them. This works for both built-in and plugin targets.

Configuration

Each conversion value can be either a boolean (applies to both project and global scope) or a per-scope object:

conversions:
  commands_to_skills:
    codex-cli: true       # both scopes — project commands as skills (default: true)
    crush: true
    zed: true

  agents_to_skills:
    goose: true           # both scopes
    windsurf:             # per-scope: convert in project mode, skip in global
      project: true
      global: false
    warp: true

Why conversions exist

Not all AI tools support all feature types natively. When a tool lacks native support, AgentsMesh can project the feature into a compatible format that the tool understands, while preserving enough metadata to round-trip back to canonical form on import.

Example: Codex CLI has no native command support. With commands_to_skills: { codex-cli: true }, AgentsMesh embeds each command as an invokable skill in AGENTS.md with a special metadata comment. When you later run agentsmesh import --from codex-cli, the importer reads the metadata and restores the original commands/*.md files.

`commands_to_skills`

Controls whether commands are projected as skills for tools without native command support.

Only targets that declare supportsConversion: { commands: true } are configurable here. A target whose commands capability is already Native ignores the setting entirely.

Target	Default	Notes
`amp`	`true`	Commands projected as embedded skills.
`aider`	`true`	Aider has no command format; conversion is the only way commands reach it.
`codebuff`	`true`	Commands projected as embedded skills.
`codex-cli`	`true`	Commands embedded as skills in `AGENTS.md`.
`crush`	`true`	Commands projected as embedded skills.
`deepagents-cli`	`true`	Commands projected as embedded skills.
`goose`	`true`	Commands projected as embedded skills.
`kimi-code`	`true`	Commands projected as embedded skills.
`kiro`	`true`	Commands projected as embedded skills.
`replit-agent`	`true`	Commands projected onto the repo-committed `.agents/skills/` surface.
`warp`	`true`	Commands projected as embedded skills.
`zed`	`true`	Commands projected as embedded skills.

Set to false to skip the target entirely (the command is not included in that tool’s output):

conversions:
  commands_to_skills:
    codex-cli: false   # skip commands for Codex CLI entirely

`agents_to_skills`

Controls whether agents are projected as skills for tools without native agent support.

Only targets that declare supportsConversion: { agents: true } are configurable here. A target whose agents capability is already Native ignores the setting entirely.

Target	Default	Notes
`amp`	`true`	Agents embedded as skills.
`aider`	`true`	Aider has no subagent format; conversion is the only way agents reach it.
`cline`	`false`	Project agents are native (`.cline/agents.yaml`), so the setting only has an effect in global mode, where it is opt-in.
`crush`	`true`	Agents embedded as skills.
`goose`	`true`	Agents embedded as skills.
`pi-agent`	`true`	Agents embedded as skills.
`replit-agent`	`true`	Agents projected onto the repo-committed `.agents/skills/` surface.
`rovodev`	`true`	Agents embedded as skills.
`warp`	`true`	Agents embedded as skills.
`windsurf`	`true`	Agents embedded as skills.

Set to false to skip:

conversions:
  agents_to_skills:
    windsurf: false   # skip agents for Windsurf entirely

Per-scope conversions

When you need different behavior for project and global mode, use an object instead of a boolean:

conversions:
  commands_to_skills:
    codex-cli:
      project: true    # convert commands in project mode
      global: false    # skip commands in global mode

If a scope key is omitted, the builtin default applies for that scope. For example, { project: false } disables project-scope conversion but leaves global-scope at its default (which for codex-cli is true).

A plain boolean (true / false) applies to both scopes — it’s shorthand for { project: <value>, global: <value> }.

Plugin targets

Conversions work with plugin targets the same way they work with built-in targets. Any plugin that declares supportsConversion in its descriptor can be configured here:

plugins:
  - id: foo-ide
    source: agentsmesh-target-foo-ide

conversions:
  commands_to_skills:
    foo-ide: true       # works for any plugin target ID
  agents_to_skills:
    foo-ide: true

When a plugin declares supportsConversion: { commands: true } and the user has not set an explicit override, the conversion defaults to true. Set to false to disable it.

Lossless round-trip guarantee

When true, projected features carry embedded AgentsMesh metadata (in YAML comments or special marker sections). This metadata is used by agentsmesh import to restore the original canonical form. No data is lost.

When false, the feature is silently omitted for that target. It will not round-trip on import — the feature simply won’t exist in that tool’s output.