Custom agent definitions loaded from YAML/markdown files.
An agent is a named bundle of run options — model, provider,
tools, permissions, mode, isolation strategy, and a system-prompt
addendum — that callers can spawn by name via
ExAthena.Tools.SpawnAgent.execute/2 with agent: "<name>".
This is opencode's .opencode/agents/<name>.md pattern adapted to
ex_athena. The Claude Code paper documents the same idea
(.claude/agents/*.md) for delegating bounded tasks.
Layout
~/.config/ex_athena/agents/<name>.md # user-level
<cwd>/.exathena/agents/<name>.md # project-level
priv/agents/<name>.md # builtin fallbacks (ship with the package)Project agents override user-level agents with the same name; the
built-in fallbacks (general, explore, plan) are used only
when the host hasn't defined one with the same name.
Frontmatter schema
---
name: explore
description: Read-only fast investigation
model: claude-haiku-4-5
provider: anthropic
tools: [read, glob, grep, web_fetch]
permissions: plan
mode: react
isolation: in_process
---
You are a read-only research assistant. Walk the codebase and
report findings concisely. Do not modify any files.Only name is required. Anything else inherits from the spawning
parent (provider, model, tools, etc.) or hard-coded defaults
(mode: :react, isolation: :in_process, permissions: :default).
Summary
Functions
Apply a definition's frontmatter to a base keyword list of run options. Definition fields override the parent's values when set; unset fields pass through.
Discover all agent definitions for cwd.
Look up an agent by name. Returns {:ok, def} or {:error, :not_found}.
Functions
@spec apply_to_opts( ExAthena.Agents.Definition.t(), keyword() ) :: keyword()
Apply a definition's frontmatter to a base keyword list of run options. Definition fields override the parent's values when set; unset fields pass through.
@spec discover( String.t(), keyword() ) :: %{required(String.t()) => ExAthena.Agents.Definition.t()}
Discover all agent definitions for cwd.
Returns a map keyed by name. Resolution: builtin → user → project, later sources overriding earlier ones.
Options
:user_dir— override the user-level agents directory.:project_dir— override the project-level directory.:builtin_dir— override the builtin fallbacks (mainly for tests).
@spec fetch(map(), String.t()) :: {:ok, ExAthena.Agents.Definition.t()} | {:error, :not_found}
Look up an agent by name. Returns {:ok, def} or {:error, :not_found}.