Agent skills should be compiled, not just read · Sigil blog

AI agents have become remarkably capable. They can write code, analyze documents, call APIs, search repositories, operate tools, and complete tasks that require several stages of reasoning.

However, there is still a major difference between completing a task once and following the same procedure reliably every time .

Consider a skill that tells an agent to run the complete test suite, inspect the output and exit code, confirm that no tests failed, and only then report that the task is complete. A model can correctly interpret every instruction, yet still report that the tests passed without actually running the test suite.

The issue is not necessarily that the model misunderstood the task. The issue is that the procedure exists only as text inside the model's context .

SIGIL

Don't prompt the skill. Compile it.

SKILL.md → AG-IR → agent.jac

sigilagent.com →

The rise of SKILL.md

Agent skills have emerged as a practical way to package reusable procedures. Instead of placing every instruction inside one large system prompt, developers can create a SKILL.md file that explains:

When the skill should be used

Which steps should be followed

Which tools should be called

What result should be produced

This is a useful authoring model. Markdown is readable, editable, versionable, and easy to share . It allows developers and domain experts to describe complex workflows without building a custom agent implementation for every task.

Skills are still read, not executed

However, when a skill is invoked, its instructions are still loaded into the model's context. The model reads the procedure and decides how to carry it out. Nothing in the normal prompt-based execution model guarantees that every required step will happen.

This limitation is already visible in industry guidance. OpenAI's guidance for evaluating agent skills recommends checking not only the final output, but also whether the agent:

Triggered the correct skill

Ran the expected commands

Followed the intended sequence

The examples include agents skipping installation commands, performing steps in the wrong order, or failing to invoke the skill reliably.

Anthropic makes a similar distinction between instructions and enforcement . Instructions placed in context can guide the model, but actions that must always be blocked or required generally need programmatic mechanisms such as hooks.

The important distinction is simple: a skill can describe a procedure without guaranteeing that the procedure is executed.

Our research found the same pattern across a wider set of tasks. Agents could read and explain their skills correctly while still:

Skipping mandatory checks

Describing tool calls they never made

Collapsing a multi-stage procedure into a single output

This leads to a natural question: what if we compiled SKILL.md into an agent harness, so that the required procedure became part of the program instead of remaining advice inside the prompt?

What compiling a skill actually means

Compiling a skill means turning the enforceable parts of SKILL.md into executable control flow. Required tool calls become program operations, validation steps become gates, and ordering constraints become part of the workflow.

Teams can already build these harnesses manually, but that means maintaining both the Markdown skill and a separate implementation. SIGIL automates this process by compiling the skill into a typed, runnable agent harness.

textCopy<br>SKILL.md<br>Extract the procedure<br>Validate the required steps<br>./agent

The model still handles tasks that require judgment, such as writing, summarizing, and interpretation. Deterministic operations, such as running commands, checking exit codes, reading files, and writing required artifacts, are handled by code.

How SIGIL compiles a skill

The compiler begins by extracting the requirements from the skill. Each extracted rule must point back to an exact passage in the original SKILL.md, which helps prevent the compiler from silently inventing requirements that were never present in the source.

SIGIL then converts the procedure into AG-IR , a typed intermediate representation for agent workflows. AG-IR records:

The steps in the procedure

The order in which they execute

The data passed between them

Which actions are mandatory or optional

Whether each operation belongs to code or the model

From a prose skill to an executable agent harness. SIGIL first extracts a grounded AG-IR graph from SKILL.md, where each step is assigned an owner and a modality. It then mechanically lowers that typed graph into a Jac agent harness with explicit control flow, gates, and typed model operations. Source: SIGIL paper.

One of the central ideas is the Owner Test :

Is the result of this step determined by its inputs?

When the answer is yes, code should own the step . Running a test command, reading an exit code, fetching a specified endpoint, or writing a file to a...