Package Structure

Every Selu agent is a self-contained directory (or Git repository) with a well-defined structure. The orchestrator reads this structure at install time to register the agent, its system prompt, and any bundled capabilities.

Minimal layout

At minimum, an agent package contains two files:

Directorymy-agent/
- agent.yaml
- agent.md

agent.yaml — The machine-readable manifest. It declares the agent’s name, version, routing rules, capability references, and metadata for the marketplace.
agent.md — The system prompt. This Markdown file is injected at the start of every LLM conversation and defines the agent’s personality, instructions, and behavioural constraints.

Full layout with capabilities and localization

Most useful agents also ship with one or more capabilities and optional localization support:

Directorymy-agent/
- agent.yaml
- agent.md
- agent.de.md
- Directoryi18n/
  - de.yaml
  - es.yaml
- Directorycapabilities/
  - Directoryweather/
    manifest.yaml
    prompt.md
    prompt.de.md
    Dockerfile
    server.py
    capability.proto
  - Directorycalendar/
    manifest.yaml
    prompt.md
    Dockerfile
    server.go

Each sub-directory inside capabilities/ is a standalone capability with its own manifest.yaml, optional prompt.md, a Dockerfile, and whatever source code it needs.

File roles

File	Required	Purpose
`agent.yaml`	Yes	Agent metadata, routing, capability list
`agent.md`	Yes	System prompt sent to the LLM
`agent.<locale>.md`	No	Localized system prompt for specific languages (e.g. `agent.de.md`)
`i18n/<locale>.yaml`	No	Localization bundle containing translated names, descriptions, and UI text
`capabilities/*/manifest.yaml`	Per capability	Capability metadata, resource limits, parameters
`capabilities/*/prompt.md`	No	Extra instructions appended to the system prompt when this capability is available
`capabilities/*/prompt.<locale>.md`	No	Localized capability prompt (e.g. `prompt.de.md`)
`capabilities/*/Dockerfile`	Per capability	Builds the container image for the capability’s gRPC server

Localization support

Agents can provide localized content to improve the user experience in different languages:

Localized system prompts

Create language-specific system prompts by adding files like:

agent.de.md for German
agent.fr.md for French
agent.es.md for Spanish

The orchestrator automatically selects the appropriate version based on the user’s language preference, falling back to the default agent.md if no localized version exists.

Localization bundles

The i18n/ directory contains YAML files with translated text for UI elements:

agent:
  name: "Wetter-Assistent"
  description: "Hilft bei Wettervorhersagen und Wetterwarnungen"

install_steps:
  api_key:
    label: "API-Schlüssel"
    description: "Geben Sie Ihren Wetter-API-Schlüssel ein"

automation:
  schedules:
    daily_forecast:
      label: "Tägliche Wettervorhersage"
      prompt: "Gib mir die Wettervorhersage für heute"
      cron_description: "Jeden Tag um 07:00 Uhr"

capabilities:
  weather:
    tools:
      get_forecast:
        display_name: "Wettervorhersage abrufen"
        description: "Ruft die aktuelle Wettervorhersage für einen Ort ab"
    credentials:
      WEATHER_API_KEY:
        description: "API-Schlüssel für den Wetterdienst (von openweathermap.org)"

approval:
  tools:
    weather__get_forecast:
      label: "Wettervorhersage abrufen"
      message: "Ich möchte die Wettervorhersage für den angegebenen Ort abrufen."

Localized capability prompts

Similar to agent system prompts, capabilities can have localized versions:

capabilities/weather/prompt.de.md for German capability instructions
capabilities/weather/prompt.fr.md for French capability instructions

Conventions

The root directory name doesn’t matter — the id field in agent.yaml is the canonical identifier.
Locale codes follow standard language tags (e.g., de for German, en-US for US English).
Capabilities can also be referenced by Docker image URI instead of bundled locally. See the agent.yaml Reference for details.
Keep agent.md focused and under 2,000 tokens. Long system prompts increase latency and cost.
Localized content should maintain the same structure and intent as the original.

Next steps

Dive into the individual file references: agent.yaml, agent.md, and Routing & Sessions.

For localization details, see Agent Internationalization.