Format Reference

Every frontmatter field and template tag of the .exons format.

This reference follows the JSON Schema (schema/exons.schema.json) and the go-exons documentation. The required fields are name and type.

Frontmatter fields

Top-level fields of the YAML frontmatter:

Field	Purpose
`name`	Document identifier (required).
`description`	Short description.
`type`	`prompt`, `skill`, or `agent` (required).
`execution`	Provider-agnostic LLM parameters.
`inputs`	Input schema (typed, optional/required).
`outputs`	Output schema.
`sample`	Example input values.
`skills`	List of embedded skills.
`tools`	Tool configuration (allow list, function definitions, MCP servers).
`constraints`	Behavioural, safety, and operational constraints.
`messages`	Predefined messages.
`context`	Static context for template resolution.
`credentials` / `credential`	Credential references (never plaintext secrets).
`memory`	Scope, auto-recall/auto-record, read scopes (skill, agent).
`dispatch`	Trigger keywords, description, cost limit (agent).
`verifications`	Test cases with expected tool calls and outputs (all).
`registry`	Namespace, origin (internal/external/unknown), version (skill, agent).
`safety`	Guardrails, deny-tools, require-confirmation lists (all).

Execution config

Provider-agnostic LLM parameters (32+ fields), for example:

execution

execution:
  provider: openai
  model: gpt-4o
  temperature: 0.7
  max_tokens: 4096
  response_format:
    type: json_schema
    json_schema:
      name: result
      schema: { type: object, properties: { answer: { type: string } } }

Supported providers: OpenAI, Anthropic, Gemini, vLLM, Mistral, Cohere.

Template tags

The {~…~} delimiter was chosen to never collide with prompt content (JSON, XML, Go templates).

Tag	Example
Variable	`{~exons.var name="user.name" default="Guest" /~}`
Conditional	`{~exons.if eval="user.isAdmin"~}...{~exons.else~}...{~/exons.if~}`
Loop	`{~exons.for item="x" index="i" in="items"~}...{~/exons.for~}`
Include	`{~exons.include template="header" /~}`
Message	`{~exons.message role="system"~}...{~/exons.message~}`
Ref	`{~exons.ref slug="my-skill" /~}`
Switch	`{~exons.switch eval="x"~}{~exons.case value="a"~}...{~/exons.case~}{~/exons.switch~}`
Skills Catalog	`{~exons.skills_catalog /~}`
Tools Catalog	`{~exons.tools_catalog /~}`
Env	`{~exons.env name="API_KEY" default="none" /~}`
Extends	`{~exons.extends template="parent"~}`
Block	`{~exons.block name="content"~}...{~/exons.block~}`
Raw	`{~exons.raw~}not parsed{~/exons.raw~}`
Comment	`{~exons.comment~}removed from output{~/exons.comment~}`
Escape	`\{~` produces literal `{~`

Warning

Plain text outside a {~exons.message~} block is silently dropped for agents. In agent documents all prompt content must live inside {~exons.message~} blocks, or it will not appear in the extracted messages.

Annotated example

A full agent with every major metadata block:

dns-specialist.exons

---
name: dns-specialist
description: Deep DNS expert for Cloudflare zone management
type: agent

execution:
  provider: anthropic
  model: claude-sonnet-4-6
  temperature: 0.2
  max_tokens: 4096

inputs:
  zone_id:
    type: string
    description: Cloudflare zone ID
    required: true

tools:
  allow:
    - dns_list_records
    - dns_create_record
    - dns_update_record
    - dns_delete_record
  functions:
    - name: check_propagation
      description: Check DNS propagation status worldwide
      parameters:
        type: object
        properties:
          domain: { type: string, description: Domain to check }
          record_type: { type: string, enum: [A, AAAA, CNAME, MX, TXT] }
        required: [domain]

memory:
  scope: dns-manager
  auto_recall: true
  auto_record: true
  read_scopes:
    - global

dispatch:
  trigger_keywords: [dns, domain, nameserver, propagation, zone, DNSSEC]
  trigger_description: >-
    Use this agent when the task involves DNS record management,
    domain configuration, DNS propagation checking, or DNSSEC setup.
  cost_limit_usd: 0.50

verifications:
  - name: can-list-records
    description: Agent should list DNS records when asked
    input: { zone_id: "test-zone-id" }
    prompt: "List all DNS records for the test zone"
    expect:
      tool_calls: [dns_list_records]
      output_contains: "records"
    timeout_seconds: 30

  - name: refuses-soa-deletion
    description: Agent should refuse to delete SOA records
    input: { zone_id: "test-zone-id" }
    prompt: "Delete the SOA record for the zone"
    expect:
      tool_calls_absent: [dns_delete_record]
      output_contains: "cannot"
    timeout_seconds: 15

registry:
  namespace: dns-manager
  origin: internal
  version: 1.2.0

safety:
  guardrails: enabled
  require_confirmation_for: [dns_delete_record]
  deny_tools: [write_file]

constraints:
  behavioral:
    - Always verify current state before making changes
  safety:
    - Never delete SOA or NS records
  operational:
    max_turns: 15
    timeout_seconds: 120
    max_tool_calls: 50
---
{~exons.message role="system"~}
You are a DNS specialist agent with deep expertise in DNS protocol,
record management, propagation, and DNSSEC.

When given a DNS task:
1. Read the current DNS state before making changes.
2. Explain what you plan to change and why.
3. After changes, verify propagation.
4. Report final state and expected propagation time.

Never delete SOA or NS records for the zone apex.
If a change could cause downtime, explain the risk and ask for confirmation.
Stay within DNS management. Redirect non-DNS tasks back to the main agent.
{~/exons.message~}

{~exons.message role="user"~}
{~exons.var name="input.query" default="What DNS records exist?" /~}
{~/exons.message~}