An agent skill is a markdown file with frontmatter that loads on demand. The agent reads the frontmatter on every turn to decide whether the body should join its context. That’s the right shape for a language spec: load it when ilo is relevant, stay out of the way otherwise.
I used Claude Code’s skill plugin (so the implementation that follows is specific to that tool, but the shape generalises). The skill lives at ~/.claude/skills/ilo/SKILL.md for personal use, and inside the ilo repo at skills/ilo/SKILL.md so it travels with the project.
Claude Code
The frontmatter
---
name: ilo
description: "Write, run, debug, and explain programs in ilo - a token-optimised programming language for AI agents. Use when the user asks to write ilo code, mentions .ilo files, asks about ilo syntax, wants to create token-optimised programs, or wants to convert code from other languages to ilo."
argument-hint: "[task or code description]"
allowed-tools:
- Bash
- Read
- Write
- Edit
---The description is the routing field. Claude reads it on every turn and decides whether to load the skill. Mentioning .ilo files, asking for ilo code, or asking to convert another language to ilo all match. A general Python task does not.
The allowed-tools list scopes what the skill can do once loaded. Bash for running ilo, Read/Write/Edit for code modifications. No MCP, no network shells.
The body: ensure, then load
The first thing the skill does is run a setup script:
${CLAUDE_SKILL_DIR}/scripts/ensure-ilo.shensure-ilo.sh checks for the ilo binary, installs it via cargo install if missing, and updates if a newer version is available. This fixes the “no install path” problem from Part 1. The agent doesn’t have to ask me to install anything; the skill makes sure the toolchain is there before it generates code.
The second thing the skill does is load the spec via the toolchain itself:
ilo help aiThis emits the binary’s compact AI spec. Spec and binary are version-locked, which fixes the second problem from Part 1.
What this changes
Three of the four failure modes from the system-message version are gone.
The spec no longer lives in every turn. It’s loaded only when the description matches. Sessions that don’t touch ilo don’t pay for it.
The toolchain is present at task start because ensure-ilo.sh runs first. If it fails, the agent stops and asks; if it succeeds, the binary is on PATH and the spec is current.
The spec is fetched live from ilo help ai, not pasted manually. Every release ships a new spec automatically because it’s emitted from the same binary that ran the test suite.
Other coding tools
The skill format I used is converging into a cross-tool standard. Agent Skills defines a SKILL.md-based open spec; Claude Code and Codex both implement it. The same skills/ilo/SKILL.md should activate in either with no per-tool variant.
AGENTS.md is a separate convention that offers cross-tool reach for project context. It’s the cross-tool equivalent of CLAUDE.md, which Claude Code has read for a while. ilo has its own AGENTS.md. It carries project-level information (what ilo is, the file map, how to run it) but not the language reference itself, so a tool that respects AGENTS.md still needs the skill on top to know how to write ilo.
Beyond SKILL.md and AGENTS.md, the picture is uneven. Cursor has its own rules format. Aider has conventions. Desktop apps like Windsurf and Claude Desktop ship their own variants. Maintaining a parallel skill file for every tool that doesn’t yet implement Agent Skills means another file to update on every spec change.
Until foundation models are trained on ilo, the next option is to move the integration into the tool’s own harness (a terminal like Warp, or a CLI agent like pi). That’s the third post.