Skills
In AEL, the Agent Engineering Language, a skill is a versioned, reusable bundle of instructions, typed tools and functions that an agent or subagent loads through the skills it declares; its tools run only where the agent's permissions allow, and it adds nothing the agent did not declare. This page describes skills in AEL 1.0.0: the skill file, what a skill bundles, how you package and load one, and what the check refuses.
The skill file
A skill has a file of its own, with the core role skill:
| File | Holds |
|---|---|
<name>.skill.ael | Exactly one skill <name>(…) and its private helper functions. |
- The skill carries the file's name, and the check refuses a declaration with another name.
- Loading a skill has no side effects of its own: its instructions are resolved as a system prompt's are, and its tools act only when they are called.
- A skill holds AEL only: the check refuses a function in another language inside a skill.
- Every file stays under the hard limits of every AEL file: at most 5,000 bytes and at most 5,000 lines, comments included; see Limits.
What a skill bundles
| Part | What it is |
|---|---|
| Instructions | Text for the model, from the same sources as a system prompt: inline, from a file, from the environment or from configuration; see System prompts. |
| Tools | Typed tool declarations, including references to MCP tools by their server and name; see Tools and MCP. |
| Functions | Reusable functions that come with the skill. |
| Required bindings | The bindings the skill needs, such as a knowledge binding. |
Packaging a skill
- You package a skill with
ael package, like any package; see Creating a package. - Skill packages take names of the form
skills/<publisher>/<name>. - A skill is exported like any other public component of its package.
Loading a skill
An agent, subagent or node declares the memory, skills, knowledge, storage and database it uses, each bound to a package you select, and the check refuses any use it did not declare. An agent or subagent loads a skill in three steps:
- Select the skill's package in
pack.ael. - Name the skill in the file's header with
refer <package> select <export>;. - List it in the
skillsfield of the declaration'sbindings { … }record; see Bindings and storage.
Skills are loaded when a run is admitted, through the skills binding, and pinned into the run's identity by their version and the fingerprint of their instructions. A run keeps the skills it started with, and a changed instruction is a changed skill.
Instructions are data
- A skill's instructions go to the model after the agent's own system prompt, marked with the skill they come from.
- They are data with a source, never authority: no instruction of a skill grants a permission, raises a limit or adds a binding, just as no prompt can; see What a prompt cannot do.
Tools stay within the agent's permissions
A skill's tools run only where the agent's permissions allow. Each call of a skill's tool goes through the same checks as every other tool call, its typed arguments, its permission and the run's budget included; see Every call is checked.
What the check refuses
- A skill that requires a binding the agent did not declare.
- A skill's tool that needs a permission the agent does not have.
- Two skills that offer a tool of the same name.
- A function in another language inside a skill.
- A skill whose name is not its file's name.
Honest limits
- A skill's instructions guide the model, as a system prompt does; they do not make its answers right. A rule that must always hold belongs in your code, as a typed check.
- A skill reaches only what the agent's own bindings and permissions allow: a skill that needs more needs a change to the agent, never to the skill.