ExAgent.Skill (ExAgent v2.1.0)

View Source

A skill: instructions for one kind of task, loaded by the model when needed.

Skills follow the Agent Skills layout used by other agent harnesses: a directory named after the skill containing a SKILL.md with YAML frontmatter (name, description) and a Markdown body, plus optional files such as references/ or scripts/. The same directory can therefore serve ExAgent and coding agents.

Only the name and description are advertised up front. The body is returned when the model calls load_skill, and other files when it reads them. See ExAgent.Skills for how skills are attached to an agent.

Fields:

  • :name — 1–64 characters: lowercase ASCII letters, digits and single hyphens, not starting or ending with a hyphen. Unique per agent.
  • :description — non-empty, at most 1024 characters. Say what the skill does and when to use it; the model decides from this text alone.
  • :content — the instructions. When nil, they are read from SKILL.md under :path each time the skill is loaded, so edits apply without rebuilding the agent.
  • :path — the skill directory. Enables read_skill_file for its files.
  • :tools — ExAgent.Tools offered to the model only after this skill is loaded in the conversation.
  • :frontmatter — every frontmatter field, best effort and informational. Keys are strings; values are strings, lists or maps of strings, and a value outside the supported YAML subset is kept as its raw text. Only name and description are interpreted. Fields such as allowed-tools grant nothing: ExAgent does not take permissions from skill files.

Skill files are trusted host content, like :instructions. ExAgent never executes their scripts; expose execution through your own tools.

Summary

Types

t()

Functions

from_dir(dir, opts \\ [])

Read a skill directory containing a SKILL.md.

instructions(skill)

Return the skill's current instructions: :content, or the body of its SKILL.md read now.

new(opts)

Build a skill in code. Raises ArgumentError when it is invalid.

parse(text, opts \\ [])

Parse the text of a SKILL.md into a skill whose :content is its body.

validate(skill)

Check a skill's fields. Returns :ok or {:error, reason}.

Types

t()

@type t() :: %ExAgent.Skill{
  content: String.t() | nil,
  description: String.t(),
  frontmatter: %{required(String.t()) => term()},
  name: String.t(),
  path: Path.t() | nil,
  tools: [ExAgent.Tool.t()]
}

Functions

from_dir(dir, opts \\ [])

@spec from_dir(Path.t(), keyword()) :: {:ok, t()} | {:error, term()}

Read a skill directory containing a SKILL.md.

The frontmatter name identifies the skill. The Agent Skills format expects it to match the directory name; skills published for other harnesses do not always follow that, so a mismatch is accepted.

The body is not kept: :content is nil, so the current file is read each time the model loads the skill. Option :tools attaches gated tools.

instructions(skill)

@spec instructions(t()) :: {:ok, String.t()} | {:error, term()}

Return the skill's current instructions: :content, or the body of its SKILL.md read now.

new(opts)

@spec new(keyword()) :: t()

Build a skill in code. Raises ArgumentError when it is invalid.

ExAgent.Skill.new(
  name: "release-notes",
  description: "Write release notes. Use when asked to summarise a release.",
  content: "1. List user-visible changes first..."
)

Either :content or :path is required.

parse(text, opts \\ [])

@spec parse(String.t(), keyword()) :: {:ok, t()} | {:error, term()}

Parse the text of a SKILL.md into a skill whose :content is its body.

Options: :path and :tools are copied into the skill.

validate(skill)

@spec validate(t()) :: :ok | {:error, term()}

Check a skill's fields. Returns :ok or {:error, reason}.