---
draft: false
title: Conversions
description: Control how AgentsMesh projects features to tools that lack native support — commands to skills, agents to skills, and more.
---

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**:

```yaml
conversions:
  commands_to_skills:
    codex-cli: true       # both scopes — project commands as skills (default: true)
    continue: true
    junie: true

  agents_to_skills:
    cline: true           # both scopes
    windsurf:             # per-scope: convert in project mode, skip in global
      project: true
      global: false
    junie: true
    gemini-cli: 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.

| Target | Default | Notes |
|--------|---------|-------|
| `codex-cli` | `true` | Commands embedded as skills in `AGENTS.md`. |
| `continue` | `true` | Commands projected as embedded skills. |
| `junie` | `true` | Commands projected as embedded skills. |

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

```yaml
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.

| Target | Default | Notes |
|--------|---------|-------|
| `cline` | `true` | Agents embedded as skills. |
| `windsurf` | `true` | Agents embedded as skills. |
| `junie` | `true` | Agents embedded as skills. |
| `gemini-cli` | `true` | Agents embedded as skills (partial native support). |

Set to `false` to skip:

```yaml
conversions:
  agents_to_skills:
    cline: false     # skip agents for Cline entirely
```

## Per-scope conversions

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

```yaml
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:

```yaml
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.
