# 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 pi 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 | kimi_code | opencode
llm = "deepseek-flash"             # must be compatible with type
reasoning_effort = "high"          # per harness; omit for the harness's own default
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 are not spec data and have no key here: set them after launch with `sky secrets set <id> KEY=VALUE` (values are write-only, encrypted at rest).

## 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. A `slug` left over from before agents were id-addressed is ignored and dropped the next time the file is stamped.