{"slug": "agent-skills-should-be-compiled-not-just-read", "title": "Agent skills should be compiled, not just read", "summary": "SIGIL, a tool that compiles agent skills from Markdown into executable harnesses, addresses the gap between instructions and enforcement in AI agents, where procedures described in SKILL.md files are often read but not reliably executed. The compiler extracts enforceable steps, such as required tool calls and validation gates, into programmatic control flow, while the model handles judgment-based tasks. This approach, supported by industry guidance from OpenAI and Anthropic, aims to ensure agents follow multi-stage procedures consistently.", "body_md": "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.\n\nHowever, there is still a major difference between **completing a task once** and **following the same procedure reliably every time**.\n\nConsider 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.\n\nThe 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**.\n\n## The rise of `SKILL.md`\n\nAgent 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`\n\nfile that explains:\n\n- When the skill should be used\n- Which steps should be followed\n- Which tools should be called\n- What result should be produced\n\nThis 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.\n\n## Skills are still read, not executed\n\nHowever, 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.\n\nThis 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:\n\n- Triggered the correct skill\n- Ran the expected commands\n- Followed the intended sequence\n\nThe examples include agents skipping installation commands, performing steps in the wrong order, or failing to invoke the skill reliably.\n\nAnthropic 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.\n\nThe important distinction is simple: a skill can describe a procedure without guaranteeing that the procedure is executed.\n\nOur research found the same pattern across a wider set of tasks. Agents could read and explain their skills correctly while still:\n\n- Skipping mandatory checks\n- Describing tool calls they never made\n- Collapsing a multi-stage procedure into a single output\n\nThis 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?**\n\n## What compiling a skill actually means\n\nCompiling a skill means turning the enforceable parts of `SKILL.md`\n\ninto executable control flow. **Required tool calls become program operations, validation steps become gates, and ordering constraints become part of the workflow.**\n\nTeams 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.\n\n```\nSKILL.md\n    ↓\nExtract the procedure\n    ↓\nValidate the required steps\n    ↓\n./agent\n```\n\nThe 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.\n\n## How SIGIL compiles a skill\n\nThe compiler begins by extracting the requirements from the skill. Each extracted rule must point back to an exact passage in the original `SKILL.md`\n\n, which helps prevent the compiler from silently inventing requirements that were never present in the source.\n\nSIGIL then converts the procedure into **AG-IR**, a typed intermediate representation for agent workflows. AG-IR records:\n\n- The steps in the procedure\n- The order in which they execute\n- The data passed between them\n- Which actions are mandatory or optional\n- Whether each operation belongs to code or the model\n\nFrom a prose skill to an executable agent harness.SIGIL first extracts a grounded AG-IR graph from`SKILL.md`\n\n, 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].\n\nOne of the central ideas is the **Owner Test**:\n\nIs the result of this step determined by its inputs?\n\nWhen 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 required location are all determined operations.\n\nWhen a step requires interpretation, synthesis, taste, or open-ended reasoning, **the model should own it**. Writing a summary, evaluating a design, or choosing between several valid approaches are examples of model-owned work.\n\n| Step | Owner |\n|---|---|\n| Run a test command | Code |\n| Read the exit code | Code |\n| Fetch a specified API endpoint | Code |\n| Summarize findings | Model |\n| Evaluate whether a design is compelling | Model |\n\nOnce AG-IR has been created, SIGIL runs a set of compile gates. These gates check whether:\n\n- Every mandatory rule is represented\n- Required artifacts are actually produced\n- Approval stages genuinely block execution\n- Deterministic operations have been hidden inside large model prompts\n\nIf the graph does not faithfully represent the skill, **compilation fails with diagnostics** instead of silently producing an incomplete agent.\n\nAfter the graph passes these checks, SIGIL mechanically lowers AG-IR into Jac. The final lowering stage does not ask another model to reinterpret the procedure. It translates the accepted graph into a runnable agent program.\n\n## Why this matters\n\nIn a normal prompt-based skill, the model controls both the reasoning and the procedure. It decides what to do, whether a required step is necessary, and when the task is complete.\n\nIn a compiled skill, **the graph controls the procedure**. The model still performs the cognitive work inside individual steps, but it cannot skip structurally compiled nodes simply by deciding that they are unnecessary.\n\nFor example, if a skill requires tests to be run before completion, the generated harness can:\n\n- Execute the test command\n- Capture the exit code\n- Inspect the output\n- Allow the success path only when verification passes\n\nThe agent does not merely receive an instruction saying that verification is important. **Verification becomes part of the program.**\n\n## Evaluation results\n\nWe evaluated SIGIL across **30 agent skills** covering document workflows, software processes, developer tools, and compliance-oriented tasks. Each run was measured using **Applicable-Mandate Compliance**, which calculates the percentage of required steps that applied to the task and were actually completed.\n\nWith GPT-4o, agents reading skills as prose completed **56 percent** of the applicable required steps on average. When the same skills were compiled with SIGIL, this increased to **86 percent**. With GPT-5, prose execution improved to **68 percent**, while SIGIL remained at **86 percent**.\n\n| Execution method | GPT-4o average | GPT-5 average |\n|---|---|---|\n`SKILL.md` read as prose |\n56% | 68% |\nSIGIL compiled harness |\n86% |\n86% |\n\nProcedure compliance across prose and compiled skill execution.The distributions show the percentage of applicable required steps completed in each run. Diamonds represent the average and horizontal bars represent the median. SIGIL achieved a median compliance of100 percent with both GPT-4o and GPT-5, meaning the typical compiled run completed every applicable required step. Source:[SIGIL paper].\n\nThe averages do not tell the entire story. For SIGIL, the median compliance score was **100 percent with both GPT-4o and GPT-5**. In other words, the typical compiled run completed every required step that applied to it. Prose execution, in comparison, was spread much more widely across the compliance range.\n\nLooking only at runs that completed the entire applicable procedure:\n\n- The prose agent succeeded in\n**28 percent** of runs - The compiled harness succeeded in\n**65 percent** of runs - This represents a\n**2.3 times increase** in complete procedure execution - At the median, compiled execution used\n**0.58 times the tokens** of prose execution\n\nThe important result is not simply that SIGIL increased the average score. **Compilation changed the shape of the results.** With prose, procedure execution varied widely from run to run. With SIGIL, full execution became the common case because the graph, rather than the model, carried the procedure.\n\nThe complete evaluation and methodology are available in the [SIGIL paper](https://arxiv.org/abs/2607.27309).\n\n## Try SIGIL\n\nInstall SIGIL on macOS or Linux:\n\n```\ncurl -fsSL https://github.com/sigilagent/sigil/releases/latest/download/install.sh | bash\n```\n\nCompile an existing skill:\n\n```\nsigil compile ./SKILL.md\n```\n\nYou can also export the compiled skill as a standalone Jac agent:\n\n```\nsigil compile ./SKILL.md -e agent.jac\n```\n\nThen run it directly:\n\n```\n./agent.jac \"extract the tables from report.pdf\"\n```\n\n## Use your existing Claude subscription\n\nIf you already use Claude Code, SIGIL can send its model calls through the authenticated Claude CLI. This allows you to compile skills **without configuring a separate Anthropic API key**.\n\n```\nsigil --claude compile ./SKILL.md\n```\n\nYou can also compile and export a standalone agent:\n\n```\nsigil --claude compile ./SKILL.md -e agent.jac\n```\n\nCompiled skills can be exposed back to Claude Code as MCP tools:\n\n```\nclaude mcp add sigil -- sigil mcp-serve\n```\n\nIn this setup:\n\n**Claude Code decides when a skill is appropriate****The compiled SIGIL harness controls how the procedure is executed**\n\n## Skills should be more than instructions\n\n`SKILL.md`\n\nis a useful authoring format because it gives developers a simple way to describe procedures and package reusable agent capabilities.\n\nBut **reading a procedure is not the same as executing it**.\n\nA required test should run because the program runs it. A required artifact should exist because a node writes it. A required approval should block execution until it is received.\n\nSIGIL keeps Markdown as the human-readable source, then compiles its enforceable requirements into a typed agent harness.\n\n**Agent skills should not only be read. They should be compiled.**\n\n## Links and resources\n\n**SIGIL website:**[sigilagent.com](https://sigilagent.com)** SIGIL documentation:**[sigilagent.com/reference](https://sigilagent.com/reference/)** Skill compilation reference:**[How SIGIL compiles](https://sigilagent.com/reference/skill-compilation.html)`SKILL.md`\n\n**SIGIL GitHub repository:**[github.com/sigilagent/sigil](https://github.com/sigilagent/sigil)** SIGIL research paper:**[SIGIL: Compiling Agent Skills into Typed Harnesses](https://arxiv.org/abs/2607.27309)** Jac language website and documentation:**[jaclang.org](https://jaclang.org)** Jac GitHub repository:**[github.com/jaseci-labs/jac](https://github.com/jaseci-labs/jac)** Jaseci:**[jaseci.org](https://www.jaseci.org)", "url": "https://wpnews.pro/news/agent-skills-should-be-compiled-not-just-read", "canonical_source": "https://sigilagent.com/blog/agent-skills-should-be-compiled.html", "published_at": "2026-08-17 13:27:24+00:00", "updated_at": "2026-08-17 13:41:27.400989+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-infrastructure"], "entities": ["SIGIL", "OpenAI", "Anthropic"], "alternates": {"html": "https://wpnews.pro/news/agent-skills-should-be-compiled-not-just-read", "markdown": "https://wpnews.pro/news/agent-skills-should-be-compiled-not-just-read.md", "text": "https://wpnews.pro/news/agent-skills-should-be-compiled-not-just-read.txt", "jsonld": "https://wpnews.pro/news/agent-skills-should-be-compiled-not-just-read.jsonld"}}