SkillZip: Contract-Preserving Graph Compression for Scalable Agent Skill Libraries

arXiv:2608.056042026-08-05

A way for AI agents to load only the needed steps of their 'skill manuals' instead of the whole thing, compressed safely without breaking how they execute

As AI agents rely on more and more procedural 'skill packages' to guide their actions, loading each whole package every time wastes context and duplicates overlapping steps. SkillZip breaks skills into section-level nodes, compresses recurring procedures into reversible 'macros' that keep their execution contract (inputs, outputs, conditions, verification checks) intact, and expands only what a task actually needs. On technical and embodied agent benchmarks, it beat the strongest baseline by up to 12.2 points while achieving 3.46x compression, 99.2% dependency preservation, and 98.7% verifier reachability.

METAL MEDIA explanatory visual

SkillZip pipeline: from skill packages to a compressed executable context

Evidence statusMeasured results reported

Sec2GraphSplits skill packages into role-typed section nodes (intent, input, precondition, operation, verifier, output) connected into an executable graph.
MotifZipFinds subgraphs that recur across skills with matching boundary interfaces, dependencies, and verifier reachability, and rewrites only those into reversible macros.
PathHydrateExpands only the portion of the compressed graph a given task needs, within a fixed context budget, when a query arrives.
ReZipUpdates the compressed library over time by promoting new recurring routines or reverting risky macros based on execution success/failure evidence.

An explanatory diagram made by METAL MEDIA, not a figure supplied by the paper's authors.

What they did

Problem: as skill libraries grow, retrieving whole skill packages loads redundant overlapping procedures, plain text compression risks hiding execution-critical contracts (inputs, outputs, verification conditions), and execution graphs are only built after retrieval, so the library itself is never stored in compressed form.
Method: Sec2Graph first splits each skill package into role-typed section nodes (intent, input, precondition, operation, verifier, output, etc.) connected into an executable graph; MotifZip then finds subgraphs that recur across skills with matching boundary interfaces, dependencies, and verifier reachability, and rewrites only those into reversible 'macro' nodes.
At query time, PathHydrate expands only the portion of the compressed graph needed for the task within a fixed context budget, and ReZip updates the compressed library over time by promoting new recurring routines or reverting risky macros based on execution evidence.
Experiments were run on SkillsBench (a technical software-agent benchmark) and ALFWorld (an embodied household-agent benchmark) across multiple LLM backbones.
Results: SkillZip outperformed the strongest baseline (SkillDAG) by up to 12.2 points on ALFWorld, achieved a 3.46x compression ratio with 99.2% dependency preservation and 98.7% verifier reachability, and kept its retrieval advantage as the library scaled from 200 to 100,000 skills; on a 1K-skill library, 51.7% of tasks needed fewer than 2,000 tokens of context, with 1,000-1,500 tokens being the most common range.

Figure 1. Representative skill-library workflows.

Table 1. Main results on SkillsBench and ALFWorld. R is task reward (%) on SkillsBench or episode success rate (%) on ALFWorld. Arrows report point changes from Vector Skills. The best comparable results are in bold.
Backbone	Method	SkillsBench (19)	ALFWorld (40)
R↑	Ret@1↑	Ret@5↑	MRR↑	R↑	Ret@1↑	Ret@5↑	MRR↑
MiniMax-M2.7	Vanilla Skills	17.2 ↑6.8	–	–	–	47.1 ↓3.6	–	–	–
Vector Skills	10.4	3.6	10.8	5.8	50.7	37.9	68.6	49.2
GoS (24)	18.7 ↑8.3	50.6 ↑47.0	65.5 ↑54.7	57.3 ↑51.5	54.3 ↑3.6	56.4 ↑18.5	86.4 ↑17.8	67.9 ↑18.7
SkillDAG (1)	27.3 ↑16.9	66.7 ↑63.1	78.2 ↑67.4	71.3 ↑65.5	67.1 ↑16.4	57.9 ↑20.0	92.1 ↑23.5	71.1 ↑21.9
SkillZip	33.3 ↑22.9	73.6 ↑70.0	92.0 ↑81.2	81.3 ↑75.5	79.3 ↑28.6	85.7 ↑47.8	98.6 ↑30.0	91.2 ↑42.0
gpt-5.2-codex	Vanilla Skills	27.4 ↑5.9	–	–	–	89.3 ↓3.6	–	–	–
Vector Skills	21.5	3.6	10.8	5.8	92.9	37.9	68.6	49.2
GoS (24)	34.4 ↑12.9	50.6 ↑47.0	65.5 ↑54.7	57.3 ↑51.5	93.6 ↑0.7	56.4 ↑18.5	86.4 ↑17.8	67.9 ↑18.7
SkillDAG (1)	36.8 ↑15.3	70.1 ↑66.5	75.9 ↑65.1	73.0 ↑67.2	93.6 ↑0.7	60.4 ↑22.5	85.1 ↑16.5	69.6 ↑20.4
SkillZip	43.0 ↑21.5	74.7 ↑71.1	88.5 ↑77.7	81.0 ↑75.2	96.4 ↑3.5	90.7 ↑52.8	99.3 ↑30.7	95.0 ↑45.8

Figure 2. Overview of the SkillZip framework. Sec2Graph retains occurrence-specific sections and links compatible ones through canonical prototypes; MotifZip rewrites recurring contract-valid subgraphs as reversible macros; PathHydrate compiles a budgeted executable context; and ReZip updates the compressed library from new skills and execution feedback.

Table 9. Measured local structural construction cost after cached contract extraction. Values report aggregate wall-clock time for graph construction and MotifZip. LLM inference is excluded.
Skills	Section nodes	Graph + MotifZip↓
100	6,441	274 ms
200	10,309	436 ms
500	24,333	1.06 s
1K	48,838	1.44 s
2K	96,739	2.90 s
5K	240,080	7.78 s
10K	477,681	16.1 s
100K	4.77 M	178 s

Figure 3. Contract-extraction quality on the annotated subset. Bars show field-level F1 and exact match; dashed lines denote macro averages.

Table 10. Local retrieval and rendering cost on SkillsBench after task anchors are available. Online excludes provider inference; Rendered Tok includes fixed rendering metadata and any indivisible selected unit.
Method	Online (ms)↓	Rendered Tok↓
Vector Skills	12.1	2,834
GoS	34.6	2,517
SkillDAG	41.2	3,103
SkillZip	27.9	1,941

Figure 4. Task reward of SkillZip as the procedural-content selection budget varies on SkillsBench with MiniMax-M2.7. The dashed line marks the default 3,000-token budget.

Table 11. End-to-end trajectory cost on the default 1K-skill SkillsBench setting with MiniMax-M2.7. Values are task averages. Prompt counters aggregate all agent turns; task time spans model inference, tool and container execution, and harness interaction.
Metric	Vanilla Skills	SkillDAG	SkillZip
Total prompt↓	2,429,237	2,782,696	1,473,532
Uncached prompt↓	78,081	76,880	62,526
Cached prompt↓	2,351,156	2,705,816	1,411,006
Completion↓	34,592	31,963	20,601
Tool calls↓	32.9	36.9	28.9
Task time (s)↓	464.7	429.7	339.0
Reward↑	17.2	27.3	33.3

Figure 5. Mean rendered context on the 1K-skill SkillsBench library. Whole-skill comparisons render each retrieved package in full, whereas SkillZip hydrates dependency-closed sections.

Table 15. Case Study 1 – Retrieval trace for header normalization with row-count verification. Skill-level retrieval exposes overlapping packages, whereas SkillZip selects the shared operation and its required verifier path.
Retrieval unit	Matching evidence	Selected context	Context consequence
Skill level	Package-level similarity to both skill descriptions	Full Clean CSV and Pivot Table packages	Includes the requested routine, but also exposes missing-value repair, pivot aggregation, and competing output rules.
Section level	Operation anchor (normalize headers) and verifier anchor (row count unchanged)	Mingest with file/schema dependencies and the row-count verifier	Closes the required dependencies and verifier path without loading unrelated downstream branches.

Figure 6. Task-level distribution of the context rendered by SkillZip. Overall, 51.7% of tasks use fewer than 2,000 tokens, and 1,000–1,500 tokens is the modal interval.

Table 16. Case Study 2 – Contract-aware comparison of three textually similar routines. MotifZip accepts the two CSV occurrences because their interfaces, execution requirements, and verifier boundaries agree, while keeping the workbook occurrence separate.
Occurrence	Interface	Execution	Verification	MotifZip decision
Clean CSV	CSV + delimiter → normalized table	Infer delimiter, parse rows, normalize headers, and preserve row identity	Schema report and reachable row-count hook	Accept into Mcsv-ingest
Pivot Table	CSV + delimiter → normalized table	Same ingest routine; pivot aggregation starts after the macro output port	Schema report; downstream total verifier remains occurrence-specific	Accept into Mcsv-ingest
Formula-Safe Workbook	XLSX → formula-preserving workbook	Use a formula-aware resource and preserve formulas during normalization	Formula-integrity and row-count verifiers	Reject from the CSV macro; retain separately
Reversible rewrite Mcsv-ingest keeps occurrence-specific source/port maps and downstream verifiers.

Figure 7. Failure attribution grouped by the earliest blocking stage.

Table 17. Case Study 3 – Illustrative ReZip trace. Repeated compatible occurrences promote a residual, while execution risk triggers controlled macro demotion.
Stage	Incoming signal	Contract evidence	ReZip update	Resulting library state
Insert	A new Merge Monthly Reports skill arrives	Ingest matches Mcsv-ingest; the align–merge–balance subgraph is unmatched	Reuse the ingest macro and buffer the residual	Known structure is compressed; novel steps remain explicit
Promote	The merge residual recurs in later skills	Ports, dependencies, resource family, and balance verifier remain stable	Promote Mperiod-merge	Later skills reuse one verified period-merge routine
Revise	Formula-bearing tasks repeatedly expand or fail the generic export macro	Failures localize to the XLSX resource and formula-integrity verifier	Split by resource family; require full source for XLSX	CSV export remains compact; workbook safeguards are restored
Reuse	A future CSV or workbook query arrives	Task anchors identify the required resource and verification contract	Select the macro and hydration level by task contract	Compact where stable; source-expanded where evidence indicates risk

Findings

On SkillsBench and ALFWorld, SkillZip outperformed the strongest baseline (SkillDAG) by up to 12.2 points (episode success rate on ALFWorld).
SkillZip achieved a 3.46x compression ratio and a 71.0% reduction in active storage while retaining 99.2% dependency preservation and 98.7% verifier reachability.
Retrieval performance advantages held as the skill library scaled from 200 to 100,000 skills.
On the 1K-skill library, 51.7% of tasks were handled with fewer than 2,000 tokens of rendered context, with 1,000-1,500 tokens being the most common interval.
SkillZip was applied as a plug-and-play layer across six different LLM backbones without backbone-specific fine-tuning.

Where it can be used

Teams building AI agents with large libraries of documented procedures (spreadsheet cleaning, verification routines, robotic manipulation steps) could reference this approach to save context budget while avoiding redundant loading of overlapping procedures.
Services where skill libraries keep growing and execution logs accumulate could reference the ReZip idea for maintaining compressed macros: promoting new reusable routines and reverting ones that turn out risky.
The framework's application across both a technical coding/data-processing benchmark and an embodied household-robot benchmark could inform experiment design for testing similar compression approaches across domains.

Limits and open work

Experiments are limited to SkillsBench (technical software agents) and ALFWorld (household robot agents); performance in other domains has not been separately verified.
Macro selection and rewriting use a greedy policy, and the paper itself states it does not claim global optimality across all overlapping motifs.
Part of the section-role classification and contract extraction relies on model-assisted parsing, so the paper does not provide detailed verification of how parsing or role-inference errors might affect compression quality.
Long-term behavior of ReZip's macro promotion, splitting, and retirement in a continuously operating large-scale production system is not presented as a separate long-term tracking experiment in the paper.

Why it matters

As skill libraries scale from hundreds to tens of thousands of entries, the cost of loading full packages and the confusion from overlapping procedures grow together, and SkillZip offers a concrete way to compress at the section level without losing the execution contract that keeps procedures safe to run. This gives practitioners building large agent skill libraries a practical direction for managing context budget and correctness at the same time.

Terms in this paper

skill package · a bundle of instructions, scripts, references, and verification rules that an AI agent loads at inference time to perform a task
procedural contract · the definition of what a procedure takes as input/output, under what conditions it executes, and how its result is verified
macro node · a compressed representation of a recurring procedural subgraph that can be reversibly expanded back to its original source sections
verifier reachability · whether a path actually exists from every state-changing operation to a verification step that checks its result
dependency preservation · how well the input, condition, and resource links between procedures are kept intact after compression

Original abstract (English)

Large Language Models (LLMs) increasingly act as agents whose procedural knowledge is stored in reusable skill packages and loaded at inference time. As skill libraries grow, a central challenge is to expose the smallest sufficient executable context under a limited context budget. Existing systems struggle to reuse routines below the whole-skill level, preserve procedural contracts during compression, keep compressed routines executable and expandable, and update the compressed library as skills evolve. These challenges reveal a unit mismatch: skills are retrieved as packages, compressed as text, and converted into execution graphs only after retrieval, whereas reliable reuse requires a contract-bearing procedural unit. We propose SkillZip, an execution-aware procedural abstraction framework that performs contract-preserving compression over section-level graphs. SkillZip rewrites recurring contract-valid motifs into reversible ported macros while preserving boundary signatures, dependency closure, verifier reachability, and source-level expansion. At inference time, it hydrates a compact, dependency-closed context and expands macros only when required. ReZip further integrates new skills and revises risky macros using execution evidence. Comprehensive experiments1 on technical and embodied agent benchmarks show SkillZip consistently outperforms the strongest baseline by up to 12.2 points, while achieving a 3.46x compression ratio with 99.2% dependency preservation and 98.7% verifier reachability. Scaling analyses further confirm robust retrieval across skill libraries ranging from 200 to 100K skills.

Authors · Xingyu Tan

Read on arXiv

Latest papers

All papers →

Latest from METAL MEDIA

Figures: Xingyu Tan et al., arXiv:2608.05604, CC BY 4.0