Agents

Agents are named personas with specialized roles. An agent defines a description and a set of instructions that an AI coding tool can assume, letting you switch between focused behaviors — an API design expert, a security reviewer, a documentation writer — without rewriting prompts.

Supported by most providers: Claude Code, Gemini CLI, Cursor, Copilot CLI, Codex, Roo Code, OpenCode, and Kiro.

Canonical Fields

Agents support the following metadata fields:

Field	Description	Provider Support
`name`	Agent name (required)	All providers
`description`	What the agent does (required)	All providers
`permissionMode`	Permission level (5 values)	Claude Code (all 5); others as prose
`effort`	Time/complexity: `min`, `moderate`, `large`, `max`	Claude Code (native); others as prose

Permission Modes

The permissionMode field supports five values:

Value	Meaning
`default`	Normal permission checking
`acceptEdits`	Auto-accept file edits
`plan`	Plan-only mode (no execution)
`dontAsk`	Skip permission prompts
`bypassPermissions`	Full bypass (use with caution)

Claude Code supports all five modes natively. Other providers embed non-native modes as behavioral prose notes.

See the Content Types overview for the full compatibility matrix.

Syllago Format

Each agent in your library has a .syllago.yaml manifest and a Markdown source file.

Manifest (.syllago.yaml):

id: 4369aa21-9660-4511-a9bb-7cea37751529
name: api-agent
type: agents
source_format: md
source_type: provider
added_at: 2026-03-13T00:13:24Z
added_by: syllago

Source file (api-agent.md):

---
name: api-agent
description: REST API design agent
---

Design RESTful endpoints with OpenAPI conventions.
Follow resource naming best practices and use proper HTTP methods.
Return consistent error shapes with appropriate status codes.

The Markdown body contains the agent’s instructions — what the AI should know and do when assuming this persona. The YAML frontmatter carries metadata (name, description) that providers use for display and selection.

Provider Format Differences

Most providers use Markdown with YAML frontmatter, so agents install with minimal transformation. Two providers use different native formats:

Codex (TOML)

Codex stores agent definitions in TOML. Syllago auto-converts between TOML and Markdown frontmatter on import and install:

[agent]
name = "api-agent"
description = "REST API design agent"

[agent.instructions]
content = """
Design RESTful endpoints with OpenAPI conventions.
Follow resource naming best practices and use proper HTTP methods.
Return consistent error shapes with appropriate status codes.
"""

When you import a Codex agent, syllago parses the TOML and stores it as standard Markdown with frontmatter. When you install to Codex, syllago converts back. No manual format handling needed.

Kiro (JSON)

Kiro uses JSON-based steering files. Syllago embeds the Markdown content into Kiro’s JSON structure automatically during install.

Workflow

# Add an agent from a provider
syllago add agents/api-agent --from claude-code

# List agents in your library
syllago list --type agents

# Install to a different provider
syllago install api-agent --to codex

# Inspect the stored format
syllago inspect api-agent