Skip to content

Capabilities

What go-exons does with a spec: parse, validate, serialize, export, and more.

go-exons parses, validates, and serializes .exons specs. It does not call an LLM — execution is the runtime’s job. Everything below operates on the spec and its template.

Parse & validate

go 
spec, _ := exons.Parse(source)       // from a string
spec, _ := exons.ParseFile("agent.exons")
err := spec.Validate()               // structural validation
err := spec.ValidateCredentialRefs() // credential references

Serialize & export

go 
out, _ := spec.Serialize(exons.DefaultSerializeOptions())
out, _ := spec.Serialize(exons.FullExportWithCredentials())
out, _ := spec.ExportToSkillMD()     // Agent Skills compatible

Multi-provider tool export

Define tools once in the spec, export to any provider’s format:

go 
for _, fn := range spec.Tools.Functions {
    fn.ToOpenAITool()    // {"type":"function","function":{...}}
    fn.ToAnthropicTool() // {"name":...,"input_schema":{...}}
    fn.ToGeminiTool()    // {"name":...,"parameters":{...}}
    fn.ToMCPTool()       // {"name":...,"inputSchema":{...}}
    fn.ToCohereTool()    // {"name":...,"parameter_definitions":{...}}
    fn.ToMistralTool()   // OpenAI-compatible
}

Template engine

A battle-tested engine (inherited from go-prompty): variables, conditionals, loops, includes, inheritance. Extend it with custom resolvers (your own tags) and custom functions usable in expressions, and resolve {~exons.ref~} references through a SpecResolver to compose agents from skills.

Catalogs

Auto-generate skill/tool catalogs and inject them into the template context, in default (markdown), detailed, compact, or function_calling (JSON schema) formats.

A2A agent cards

Generate Google A2A protocol Agent Cards from spec metadata — pure metadata transformation, no template execution or network calls. Dispatch keywords become skill tags; registry version becomes the card version.

Token estimation

go 
estimate := exons.EstimateTokens(source)
// estimate.EstimatedGPT, estimate.EstimatedClaude, estimate.EstimatedGeneric

Debug & validation

AST validation (unknown tags, missing attributes), a static dry run, and a human-readable Explain walkthrough of execution. With markdown fence mode enabled, Validate() additionally warns about tag-like syntax inside inert code fences and about unclosed fences.

Syntax safety (v0.15.0)

Templates can contain examples of their own syntax without executing them — see Format Reference for the syntax:

go 
engine := exons.MustNew(exons.WithMarkdownFences())
// fenced code blocks in markdown bodies are inert;
// a ```exons fence renders live

All markdown import paths mark specs with Spec.ContentFormat = "markdown" so consumers know to enable the option. Verbatim tilde fences {~~ ... ~~} work in every template regardless of the option, and raw blocks round-trip their bodies byte-exactly.

Security by default

The engine is hardened out of the box:

  • Env-var access control — {~exons.env~} blocks common secret patterns (*_KEY, *_SECRET, *_TOKEN, *_PASSWORD) by default; configurable allow/deny lists.
  • Output size limits — rendered output capped at 10 MB by default.
  • Zip import protection — path-traversal and decompression-bomb defenses.
  • Recursion limits — inclusion, inheritance, and ref resolution all bounded.

JSON Schema

A JSON Schema for the frontmatter ships at schema/exons.schema.json — use it in VS Code’s YAML extension or in CI. See the Format Reference.