# agent.toml reference

A fly.toml-style declaration of your agent. Optional at every layer — `sky launch` scaffolds it, a flags-only path exists for everything, and the file never crosses the wire (the CLI validates and inlines it client-side).

## Full schema

Only `name` is required; `type` defaults to hermes and `llm` to the type's default model. Long markdown can live inline in triple-quoted strings or in sibling files via `file =` / `prompt_file =` — the CLI inlines their content before calling the API.

```toml
# agent.toml — everything the create wizard can set. Only `name` is required.
name = "research-agent"
description = "Web research with citations"
type = "hermes"                    # hermes | claude_code | codex | openclaw | pi | dsh
llm = "deepseek-flash"             # must be compatible with type
capabilities = ["exa.search"]      # capability ids from the catalog
vcpus = 2                          # optional machine size for launch's first session: 1|2|4|8
memory_mb = 4096                   # 256MB steps, 256-2048MB per vCPU

# The user prompt layer; the platform preamble is composed server-side.
# Inline here, or `prompt_file = "prompt.md"`.
prompt = """
You are a meticulous research agent…
"""

[[instructions]]                   # additional .md files for the agent
name = "style.md"
file = "instructions/style.md"     # or inline: content = """…"""

[[skills]]                         # a store skill, attached by reference
type = "skill"
skillId = "skill_…"                # from POST /v1/skills
version = "latest"                 # or a revision id (skr_…) to pin

[[skills]]                         # or a GitHub repo: its root .claude/skills/
type = "github"                    # is loaded at every session start
url = "https://github.com/org/repo"
ref = "main"                       # optional branch or commit SHA

[[customData]]
id = "prices"
name = "Price sheet"
kind = "spreadsheet"               # spreadsheet | doc | private_api | other
uri = "https://…"

[[secrets]]                        # declarations only; values via `sky secrets set`
key = "NOTION_TOKEN"
env = "NOTION_TOKEN"
required = true
description = "Notion integration token"
```

## Lifecycle

`sky launch` creates the agent spec + its first session and stamps `id = "agent_…"` (the agent id — session ids never live in the file); from then on `sky deploy` re-applies your edits (prompt, display name, capabilities, skills) to the spec, idempotently — the prompt applies to sessions started after the save. `-f <path>` overrides the `./agent.toml` discovery on both commands.