Format Conversion

How Conversion Works

Syllago uses a hub-and-spoke model. Content in your library is stored in syllago format — a provider-neutral representation that syllago converts to and from each provider’s native format:

Source Provider -> syllago format -> Target Provider

When you run syllago install my-skill --to cursor or syllago convert my-rule --to windsurf, syllago:

Reads the content from your library (already in syllago format)
Converts to the target provider’s format
Translates tool names, metadata, and frontmatter automatically

Compatibility Matrix

Content Type	Coverage	Notes
Rules	Every provider	Format varies (Markdown, MDC) but content fully preserved
Skills	Most providers	Metadata rendering varies by provider capability
Agents	Most providers	Codex uses TOML format, Kiro uses Markdown with YAML frontmatter (auto-converted)
MCP configs	Every provider	Zed uses `context_servers` key (handled automatically)
Hooks	Many providers	Claude Code, Gemini CLI, Copilot CLI, Cursor, Windsurf, Codex, Cline, Kiro
Commands	Many providers	Claude Code, Gemini CLI, Cursor, Copilot CLI, Codex, OpenCode
Loadouts	Claude Code (v1)	Additional provider emitters planned

Provider-Specific Format Notes

Cursor

Rules are converted to MDC (Markdown Component) format with .mdc extension. Frontmatter fields map to MDC metadata headers.

Codex

Agent definitions use TOML format. Syllago auto-converts between TOML and Markdown frontmatter.

Kiro

Agent definitions use Markdown with YAML frontmatter (14 fields). Also supports a JSON CLI agent format with embedded MCP servers and lifecycle hooks. Rules and skills are Markdown steering files.

Amp

Rules use AGENTS.md format with globs array frontmatter. MCP configs use a provider-specific JSON key.

Zed

MCP server configs use the context_servers key instead of mcpServers. Syllago handles this mapping automatically.

OpenCode

Rules use YAML format. Syllago strips Markdown frontmatter and converts to OpenCode’s YAML structure.

What Gets Preserved

Content body — always preserved in full
Metadata — mapped to provider-equivalent fields where possible
Tool names — automatically translated (e.g., Claude Code’s Read becomes Gemini’s read_file)
Frontmatter — converted to provider-appropriate format (YAML, TOML, JSON, or embedded as prose)

When metadata can’t be represented in the target format, it’s either embedded as a comment or note in the content body, or reported as a portability warning during conversion.

Portability Warnings

Both syllago convert and syllago install surface warnings when content uses features unsupported by the target provider. Warnings appear inline in text mode and in the warnings array in JSON mode.

Common warnings include:

Unsupported hook events (e.g., Gemini’s before_model has no Claude Code equivalent)
Missing capability support (e.g., input_rewrite not available on target)
Fields dropped during conversion (e.g., disabledTools on MCP servers)

Canonical Tool Names

The canonical format uses provider-neutral tool names:

Canonical	Claude Code	Gemini CLI	Cursor
`file_read`	Read	read_file	read_file
`file_write`	Write	write_file	edit_file
`file_edit`	Edit	replace	edit_file
`shell`	Bash	run_shell_command	run_terminal_cmd
`search`	Grep	grep_search	grep_search
`find`	Glob	glob	file_search
`web_fetch`	WebFetch	web_fetch	—
`agent`	Agent	—	—

Translation happens automatically during conversion. You never need to manually adjust tool names.

Using the Convert Command

# Convert a specific item to stdout
syllago convert my-skill --to gemini-cli

# Save to a file
syllago convert my-rule --to windsurf --output ./windsurf-rule.md

# JSON output with portability warnings
syllago convert my-skill --to cursor --json

# Check compatibility across all providers
syllago compat my-skill

Hook Conversion

For hooks specifically, syllago uses the Hook Interchange Format as the canonical representation. This handles:

Event name translation between providers
Matcher type conversion (tool vocabulary, regex, MCP targeting)
Timeout unit normalization (seconds canonical, auto-converts to/from milliseconds)
Capability degradation (block, warn, or exclude based on target support)