feature: modular skills (Phase 1)#397
Merged
Merged
Conversation
First of six modules splitting the monolithic ai.txt into Anthropic Skill format. Covers the core syntax + semantics reference: prefix notation, type sigils, function decls, guards, match, pipes, records, Results. Self-contained: an agent can write or review .ilo source from this module alone. 994 tokens (cl100k_base), under the 1,000-token per-module cap. Builtin signatures, error codes, tool decls, and engine choice live in the other five modules.
Signatures and one-line examples for the most-used builtins: math, text, list, HOF, map, I/O, HTTP, JSON, time. No prose explanation, that lives in SPEC.md and the docs site. 830 tokens. Includes the asin/acos/sqrt/log silent-NaN gotcha because validating at the call boundary belongs with the call list, not buried in errors.
ILO-L###/P###/T###/R### codes with one-line cause + fix, plus the JSON diagnostic shape so an agent can route on code and patch at span without loading the long-form explanation. 685 tokens. Long-form explanations stay behind ilo --explain ILO-XXXX.
How to declare and call external tools (HTTP, MCP) from ilo: tool keyword, provider config, discovery commands, runtime flow, failure handling. 745 tokens. Most programs don't touch tools, so this module is loaded only when the task does.
Backend selection (tree, VM, JIT, AOT): when each matters, feature matrix, benchmark + compile invocation. VM is the default since v0.11 (#390); JIT and tree are opt-in. 801 tokens. This module is rarely needed by most agents, so keep it small and load it only when picking execution mode actually matters.
The agent integration surface: skill discovery, running programs, reading JSON diagnostics, the repair loop, top-level Result contract, serv mode. Teaches an agent how to USE ilo rather than how the language works. 851 tokens. This is the entry-point skill an agent loads first; it then pulls the others on demand.
Bundles the six skill modules into the binary via include_str! so they travel with every install and stay version-locked to the compiler. The new `ilo skill` subcommand is the canonical surface for granular loading: ilo skill list name + description per skill ilo skill get <name> full content (stdout) ilo skill path <name> bundled filesystem path ilo skill show <name> content with a formatted header exit 1 + 'unknown skill' on bad names `ilo -ai` still emits the full concatenated compact spec for back-compat, so existing agents that load everything keep working. marketplace.json grows a `skills` array listing all six so Claude Code's skill discovery picks them up automatically when the plugin is installed.
Two layers of defence so the per-task economics don't regress:
1. scripts/check-skill-tokens.py uses tiktoken cl100k_base, the same
tokeniser an agent host uses for context-window sizing, and is the
canonical 1,000-tokens-per-module / 5,000-tokens-total gate.
2. tests/skill_modular.rs runs inside cargo test, no Python required;
uses a conservative byte proxy plus structural checks (every file
exists, every frontmatter valid, every description starts with
'Use this when', name matches filename, marketplace lists them
all).
The Rust test catches drift even when CI is bypassed; the Python step
catches the edge cases the byte proxy can't see.
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Splits ilo's monolithic ~18,710-token
ai.txtcompact spec into six Anthropic-Skill-format modules so agents load only the slice their current task needs. Adds anilo skill list/get/path/showCLI accessor, bundles the skills into the binary viainclude_str!, and gates the per-module / aggregate token budget in CI.This is Phase 1 of the strategic work programme (zero-gap-specs/01-modular-skills.md). Without it, per-task token cost is dominated by the spec load and ilo is non-viable against Zero on cached agent workflows regardless of how dense the source is.
Token counts
ai.txt, always fully loaded)Per-module breakdown (cl100k_base):
Every module is under the 1,000-token per-module cap. Total is under the 5,000-token aggregate cap. The hard limits are enforced by
scripts/check-skill-tokens.pyin CI plus a byte-proxy + structuraltests/skill_modular.rsin the Rust test suite.What's in the diff
8 commits, one per logical step:
add ilo-language modular skill- core syntax: prefix notation, types, guards, match, pipes, records, Results, lambdasadd ilo-builtins modular skill- signatures + examples for math, text, list, HOF, map, IO, HTTP, JSON, timeadd ilo-errors modular skill- ILO-X### codes with one-line cause + fix, JSON diagnostic shapeadd ilo-tools modular skill-toolkeyword, MCP/HTTP providers, runtime flowadd ilo-engines modular skill- tree/VM/JIT/AOT backend selection, feature matrixadd ilo-agent modular skill- skill discovery, run/check invocation, repair loop, serv modewire \ilo skill list/get/path/show` and update marketplace` - CLI subcommand, marketplace.json lists all sixenforce modular-skill token budget in CI and Rust tests- tiktoken script + Rust structural testsilo -aistill emits the full concatenated compact spec for back-compat, so existing agents that load everything keep working. The newilo skill get <name>surface is the recommended path for token-sensitive agents.skills/ilo/SKILL.mdstays in place (still auto-regenerated from SPEC.md by build.rs) as the legacy single-skill entry point. The six modules sit alongside it. Retiring SKILL.md would require unwinding ~3 dozen test references and is deferred to Phase 1b.Test plan
skills/ilo/ilo-*.mdwith valid Anthropic YAML frontmatter (name,description)ilo skill listprints all six with name + descriptionilo skill get <name>prints content, unknown name exits 1ilo skill path <name>printsskills/ilo/<name>.mdilo skill show <name>prints content with headerilo -aistill works (back-compat);ai.txtunchanged on diskcargo fmt --all -- --checkcleancargo clippy --release --features cranelift --all-targets -- -D warningscleancargo test --release --features craneliftpasses (the existingregression_inline_lambdafailures pre-date this branch and are unrelated; they reproduce onmain)python3 scripts/check-skill-tokens.pyexits 0Follow-ups
skills/ilo/SKILL.mdand rewire the ~3 dozen test references to point at the modular files, or replace SKILL.md with a thin router that links to the six.