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

Xingyu Tan, Xiaoyang Wang, Qing Liu, Xiwei Xu, Xin Yuan, Liming Zhu, Wenjie Zhang

SkillZip compresses agent skill libraries into contract-preserving procedural graphs to enable scalable, executable reuse.

How can we compress large agent skill libraries while ensuring that the resulting context remains executable and contract-compliant?

Agent skill libraries grow redundant as they scale, but existing systems treat skills as indivisible text packages, forcing agents to load entire routines even when only a small, shared procedure is needed. SkillZip replaces this "retrieve-whole-package" approach with a graph-based framework that decomposes skills into source-grounded, contract-bearing sections and compresses recurring procedural motifs into reversible macros. This allows the system to hydrate only the minimal, dependency-closed subgraph required for a task, achieving a 3.46× compression ratio while maintaining 99.2% dependency preservation.

Paper Primer

The core move is a three-stage pipeline: Sec2Graph converts opaque skill packages into typed procedural subgraphs; MotifZip mines these graphs for recurring motifs and replaces them with reversible macros that explicitly record their interface, execution, and verification contracts; and PathHydrate retrieves only the necessary sections at runtime, expanding macros only when the task requires deeper detail.

SkillZip significantly outperforms state-of-the-art graph-based retrieval baselines in end-to-end task performance.

On the ALFWorld benchmark using gpt-5.2-codex, SkillZip achieved a 96.4% success rate, outperforming the strongest baseline (SkillDAG) by 2.8 points, with even larger gains (12.2 points) on smaller models. 3.46× compression ratio with 99.2% dependency preservation.

Section-level retrieval reduces ambiguity in large libraries compared to whole-skill retrieval.

As the library scales from 200 to 100,000 skills, the Ret@1 advantage of SkillZip over SkillDAG widens from 6.2 to 23.3 points.

Why is "contract-preserving" compression necessary for agent skills?

Unlike static text, agent skills are executable; compressing them as simple text can obscure preconditions, guard branches, or verifier hooks, leading to unsafe execution. SkillZip ensures that every compressed macro retains its original interface, dependency closure, and verifier reachability.

How does the system handle new skills or evolving procedures?

The ReZip component incrementally updates the library by matching new skills against existing macros, promoting recurring residual motifs into new macros only after repeated evidence, and revising or retiring macros that trigger frequent verifier failures.

For researchers building agent memory systems, SkillZip demonstrates that procedural knowledge should be managed as a persistent, contract-aware graph rather than a collection of static text files, enabling both higher retrieval precision and lower token costs.

Introduction: The Scalability Challenge

Frames the redundancy and contract‑preservation gap in large LLM skill libraries.

LLM agents rely on reusable skill packages, but as libraries grow the provider must expose the smallest sufficient executable context within a tight context budget.

Existing systems retrieve whole skill packages, compress them as text, and build execution graphs only after retrieval, creating a unit mismatch that hinders reuse, contract preservation, persistent compression, and execution‑aware maintenance.

Challenge 1 – reuse‑granularity mismatch: whole‑skill retrieval forces loading of irrelevant sections, even when multiple skills share identical procedural fragments.

Challenge 2 – contract preservation under compression: text‑level compression can obscure preconditions, guard branches, or verifier hooks, breaking the procedural contract required for safe execution.

Challenge 3 – persistent executable compression: current graph builders operate after retrieval, so recurring routines are repeatedly rediscovered and re‑verified instead of being stored as reusable compressed units.

Challenge 4 – execution‑aware maintenance: as new skills appear and execution traces reveal risky abstractions, a static compressor cannot adapt, leading to stale macros or missed reuse opportunities.

A procedural contract is the explicit contract a skill section exposes: the inputs it expects, the operations it performs, and the verifier that checks its outcome.

**Figure 1.** Representative skill-library workflows.

The core trade‑off is between fitting more procedural content into the limited context window and preserving the reliability guarantees encoded in procedural contracts.

Related Work

We survey prior work on agent skills, retrieval, and graph‑based compression.

Prior work on agent skills spans formal skill packages, retrieval mechanisms, and compression techniques. Below we organize these contributions by their primary focus.

A Vector Skill bundles a single, self‑contained capability (e.g., “search web”) together with its required inputs, outputs, and verification contract.

SKILLDAG is a directed acyclic graph whose nodes are Vector Skills and edges encode dependency or data‑flow relationships.

Formalizes reusable skill packages that bundle instructions, scripts, references, and resources into a single deployable unit.

A taxonomy that categorizes skill creation, management, retrieval, generation, and compatibility phases.

Retrieves ordered subgraphs from an evolving skill‑level dependency graph to preserve execution order.

Combines typed skill contracts with an ecosystem graph for library diagnosis and maintenance.

Methods that shorten contexts via token selection, rewriting, or compact representations, applied to both prompts and skill bodies.

Abstract successful experiences into reusable skills, rules, or memories that can be invoked later.

Techniques such as frequent‑subgraph mining, MDL‑based summaries, and grammar‑based replacement that discover and compress repeated structure.

Preliminaries

Defines the procedural skill graph and the macro‑compression trick used by SkillZip.

Skill libraries contain many sections that repeat the same procedural pattern, inflating retrieval cost and obscuring the minimal contract needed for a task.

A macro node folds a connected subgraph of sections into a single boxed unit, preserving its input‑output contract while discarding internal duplication.

Identify the subgraph as a candidate macro because its only external connection is the output edge from v₃ to the rest of the library.

Create macro node $M$₍g₎ with I₍g₎ = ∅, O₍g₎ = output of v₃, and copy the verifier from v₃ to M₍g₎.

Redirect any incoming edges to v₁ (none) and outgoing edges from v₃ to now originate from M₍g₎.

Remove v₁, v₂, v₃ and their internal edges; the graph size shrinks from 3 nodes to 1.

Macro compression eliminates internal redundancy while guaranteeing that any later verifier can still be reached through the macro’s preserved contract.

How does a macro node differ from simply grouping sections into a reusable function?

A function groups code but typically hides its I/O and verification details behind an opaque signature. A macro node explicitly records the full procedural contract (typed I/O, resource bindings, and verifier reachability) and guarantees that expanding the macro reproduces the original sections exactly, which a plain function does not assure.

When a query arrives, SkillZip selects a subgraph P₍q₎ from the compressed graph `G_zip`, then “hydrates” it—expanding any macro nodes back to their original sections—to satisfy the executor’s budget while preserving verifiers.

The SkillZip Framework

SkillZip compresses skill libraries while keeping every execution contract intact.

Large skill libraries contain duplicated procedural fragments that bloat storage and slow retrieval, yet dropping any fragment risks breaking the contract that guarantees correct execution.

SkillZip turns a sprawling collection of skill packages into a graph where each node carries its input‑output contract, then rewrites repeated contract‑compatible subgraphs into reversible macros, so an agent can fetch only the pieces it needs while still being able to expand them back to the original source.

Sec2Graph creates three section nodes $v_1,v_2,v_3$, each labelled “load‑csv” with contract $(X\!\to\!Y,\; \text{verify rows})$.

MotifZip groups the three nodes into a motif $g$ because their contracts match.

MotifZip replaces $v_1,v_2,v_3$ with a single macro node $M_g$ that records the shared contract and stores pointers to the three source locations.

PathHydrate, given a task that needs “load‑csv”, retrieves $M_g$ and expands it only for the skill that the task actually invokes.

The macro preserves the original verifier for each occurrence, so expanding $M_g$ for any skill restores the exact safety check that was present before compression.

How does SkillZip differ from a naïve deduplication that simply removes duplicate code blocks?

Naïve deduplication discards the procedural contract (guards, verifiers, resource annotations). SkillZip keeps those contracts attached to the macro, so the compressed library remains executable and safe.

**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.

Sec2Graph tackles the first obstacle: raw skill packages are too coarse to expose reusable procedural pieces.

Sec2Graph parses a skill package into a directed subgraph where each node is a typed section (operation, verifier, guard, etc.) and edges encode execution order, dependencies, and verification links, preserving a pointer back to the original source.

SegmentSkill splits the script into three candidate sections $b_1,b_2,b_3$.

InferRole labels $b_1$ as Operation, $b_2$ as Verifier, $b_3$ as Guard.

Contract extraction yields $(X_{b_1}=file, Y_{b_1}=table)$, $(X_{b_2}=table, Y_{b_2}=bool)$, $(G_{b_3}=missing\_col)$.

Edges: $b_1 arrow b_2$ (dependency), $b_2 arrow b_3$ (verifier edge), $b_3$ has a repair edge back to $b_1$.

The explicit verifier edge guarantees that any execution of the subgraph must pass the column‑count check before proceeding.

Why can’t Sec2Graph be replaced by a simple linear list of code snippets?

A linear list loses the rich dependency and verifier edges that encode execution order and safety checks; Sec2Graph’s graph preserves these relationships, which are essential for later compression and safe hydration.

MotifZip compresses the section graph by mining contract‑compatible motifs and turning them into reversible macros.

MotifZip searches the section graph for recurring typed subgraphs whose external interfaces (ports, resources, verifiers) match, then replaces each occurrence with a macro node that records the shared contract and a reversible expansion rule.

GrowMotifs groups the three nodes because they share the same role signature (Operation) and I/O shape ($X\!\to\!Y$).

Support counting confirms the three occurrences are non‑conflicting (different source pointers).

Contract validation passes: all three expose identical input/output ports and the same verifier condition.

MotifZip creates macro $M_{norm}$ with ports $(X,Y)$ and contract $\chi_{norm}$, then rewrites each occurrence to $M_{norm}$.

The macro $M_{norm}$ can be expanded back to any of the three original sections, preserving the verifier that guarantees unit norm.

How is MotifZip safer than generic frequent subgraph mining?

Generic mining ignores the procedural contract; MotifZip restricts candidates to interface‑compatible neighborhoods and validates that every external dependency and verifier remains reachable after compression.

PathHydrate assembles a minimal executable context for a given task by selecting and hydrating only the necessary macros and sections.

PathHydrate translates a natural‑language query into graph anchors, fuses section‑level and skill‑level scores to build a seed set, then searches for the smallest connected subgraph that covers the anchors while respecting a token‑budget; macros inside the subgraph are hydrated just enough to satisfy the task.

AnalyzeTask creates $z_q$ with subgoals {parse, extract, write}.

Section‑level scoring finds high‑similarity nodes for each subgoal across several skills.

RRF fuses skill‑level rankings, selecting the “date‑extraction” skill as the seed bundle.

Constrained subgraph search returns a connected subgraph containing the three anchors plus required resource nodes (file handle, schema).

Repair adds the missing verifier that checks CSV well‑formedness and the guard that validates date format.

Macro “DatePipeline” is hydrated to contract‑only level because the task does not need the full source code.

Hydrating only to contract level keeps the token budget low while still providing all safety checks required for execution.

Why doesn’t PathHydrate simply retrieve the whole skill that matches the query?

Retrieving the whole skill would exceed the token budget and may include irrelevant sections; PathHydrate composes the smallest connected subgraph that still satisfies all contracts, then expands macros only as far as needed.

ReZip closes the loop by incrementally updating the compressed library as new skills and execution traces arrive.

ReZip ingests new skills, matches their procedural subgraphs against existing macros, promotes frequently observed residual motifs into new macros, and demotes or splits macros that exhibit high failure or repair cost, thereby keeping the macro dictionary both compact and safe.

Sec2Graph creates a subgraph with an Operation node “merge” and a Verifier node “validate‑schema”.

ReZip attempts to reuse the existing macro “ValidateSchema”; the new verifier’s guard differs, so the region remains residual.

After three additional skills exhibit the same residual pattern, support $=3 \ge m$ and $\Delta(r)>0$, so ReZip promotes the residual as a new macro $M_{val}$.

During execution, $M_{val}$ records two verifier failures; $\rho_t(M_{val})$ exceeds the risk threshold, triggering a split into two macros: one for the common case, one for the edge case.

ReZip’s promotion and demotion cycles keep the macro dictionary both compact and aligned with observed verification behavior.

How does ReZip avoid the “once‑compressed‑always‑wrong” problem?

By continuously monitoring execution evidence; macros that cause frequent verifier failures are either hydrated to expose more detail or split into safer, more specific macros, ensuring the compressed library stays faithful to observed contracts.

Let $\Omega$ be a set of pairwise non‑conflicting motif occurrences accepted by MotifZip. Denote $\kappa_\Omega, \xi_\Omega$ as their simultaneous macro rewriting and source expansion. If a raw procedural subgraph $P$ contains, for each occurrence in $\Omega$, either all or none of its internal nodes, then $\xi_\Omega(\kappa_\Omega(P)) \cong P$ (up to auxiliary prototype links), and isomorphism preserves typed external dependencies and operation‑to‑verifier reachability.

Main Results

SkillZip delivers top‑line performance gains and efficient retrieval across benchmarks.

Recall that large skill libraries suffer from procedural redundancy; SkillZip compresses them into a graph while preserving execution contracts.

SkillZip outperforms all baselines on both SkillsBench and ALFWorld across two backbones, delivering up to +12.2 points higher reward or success than SkillDAG.

Table 1 shows SkillZip achieving 33.3 (SkillsBench) and 79.3 % (ALFWorld) with MiniMax‑M2.7, and 43.0 / 96.4 % with gpt‑5.2‑codex, each surpassing SkillDAG by the reported margins.

**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.

Ablation and Structural Fidelity

Compression ablations reveal which components preserve executable structure.

We evaluate whether compression can shrink the rendered skill context while preserving the dependencies and verification conditions needed for execution (RQ3). Table 3 then isolates the contribution of each component to overall performance (RQ4).

SkillZip compresses the skill graph 3.46× while keeping structural fidelity near perfect.

Table 2 shows a compression ratio of 3.46× together with DPR 99.2 and VR 98.7 for the full model.

Dropping section‑level nodes reduces Ret@1 by 6.9 points and inflates rendered tokens by 59.9 %.

Table 3 reports a 6.9‑point Ret@1 drop and a 59.9 % token increase when section‑level nodes are replaced with skill‑level nodes.

Removing MotifZip raises token count by 52.9 % and lowers reward to 31.0 points.

Table 3 shows a 52.9 % token increase and reward falling to 31.0 when MotifZip is omitted.

Disabling dependency closure leaves reward unchanged but drops DPR to 82.3 %.

Table 3 indicates DPR 82.3 after removing dependency closure.

Removing verifier constraints reduces VR to 76.4 % while Ret@1 stays high.

Table 3 reports VR 76.4 when verifier constraints are removed.

Omitting global section rescue cuts Ret@1 to 68.2 points and reward to 30.4.

Table 3 shows Ret@1 68.2 and reward 30.4 without global section rescue.

Turning off adaptive hydration inflates token usage by 33 %.

Table 3 notes a 33 % token increase when adaptive hydration is disabled.

Algorithm Details

Algorithm Details explains how SkillZip builds, compresses, and hydrates skill graphs to eliminate redundancy.

Skill libraries explode with duplicated procedural steps, inflating storage and slowing retrieval. SkillZip tackles this by extracting a compact graph that preserves every execution contract.

Build a raw section graph from each skill package (Sec2Graph).

Compress repeated procedural motifs while preserving contracts (MotifZip).

Hydrate a budget‑constrained, task‑specific execution context (PathHydrate).

Maintain the compressed library incrementally as new skills or traces arrive (ReZip).

Section grounding yields two spans $b_1$ (init) and $b_2$ (run).

Role inference assigns $\tau_{b_1}=$

Signature extraction produces $(X_{b_1},Y_{b_1})=(\emptyset,\{file\})$ and $(X_{b_2},Y_{b_2})=(\{file\},\emptyset)$.

Nodes $v_{b_1}$ and $v_{b_2}$ are created and a weak‑order edge $v_{b_1}\!arrow\!v_{b_2}$ is added.

Input binding links the output $file$ of $v_{b_1}$ to the input of $v_{b_2}$; the guard “file exists” is attached to $v_{b_2}$.

The resulting graph makes the implicit file dependency explicit, enabling safe reuse or replacement of the init section later.

How does Sec2Graph differ from merely parsing a script into a flat list of commands?

Sec2Graph enriches each command with a typed role, explicit input/output signatures, and guard edges, turning a linear list into a contract‑aware graph that can be merged, compressed, or verified without losing safety guarantees.

Bucket by signature groups the three $A\!arrow\!B$ pairs together.

GrowMotifs discovers a candidate motif $g$ consisting of the $A\!arrow\!B$ pattern.

Occurrences $\Omega_g$ are $\{(A_1,B_1),(A_2,B_2),(A_3,B_3)\}$; support $|\Omega_g|=3\ge m$.

BuildContract extracts input port $I_g=X$, output port $O_g=Y$, and verifier set $\chi_g$ (none needed).

All checks (BoundaryClear, SignatureStable, DependencyClosed, VerifierReachable) pass.

CompressionGain $\Delta(g)>0$, so a macro $M_1$ is created and the three occurrences are replaced by $M_1$.

The macro abstracts the repeated pattern while preserving the exact inputs and outputs each instance expects, enabling later reuse without breaking contracts.

Why not simply merge identical sections outright instead of creating a macro?

Merging would erase the distinct I/O ports, breaking downstream contracts that rely on those interfaces. A macro retains a single, well‑defined interface that all callers can bind to, preserving verifiability.

AnalyzeTask creates $z_q$ and builds seed queries $Q_q$ for the query.

DenseSectionScore ranks $M_1$ highest, $v_a$ second, $v_b$ third.

AdaptiveTopSeeds selects $A_q=\{M_1, v_a\}$.

ConnectSeeds links $M_1$ and $v_a$ via existing edges, forming subgraph $P$.

Scaffold repair adds missing input ports and a verifier node to $P$.

RoleBudgetPrune removes $v_b$ (exceeds budget) and DepthFill adds $v_c$ because it improves coverage without breaking budget.

RepairClosure ensures all verifiers reachable; EnforceBudget trims any excess.

RenderContract produces $C_q$ containing $M_1$, $v_a$, $v_c$ and the added scaffolds.

RecordHydration logs the selections and macro usages.

Budgeting forces the system to prioritize high‑impact macros, yielding a compact yet verifiable execution plan.

Why not retrieve the full compressed graph for every query instead of budgeting?

Fetching the whole graph defeats the purpose of budgeted execution and can re‑introduce unnecessary dependencies; PathHydrate trims to the minimal set that still satisfies contracts, keeping execution fast and safe.

**Algorithm 1: SkillZip Workflow** **Input**: Skill library $S$, update stream $U$, query $q$, profile $p$, budget $B$ **Output**: Hydrated context $C_q$, hydration log $L_q$, compressed graph $G_{zip}$ /* Stage 1: Sec2Graph: Building Procedural Subgraphs */ 1. $G \leftarrow \emptyset, M \leftarrow \emptyset, B_{res} \leftarrow \emptyset, \Sigma \leftarrow \emptyset$; 2. **for each** skill package $s \in S$ **do** 3. $\quad h_s \leftarrow \text{Sec2Graph}(s)$; 4. $\quad G \leftarrow \text{MergeSkillGraph}(G, h_s)$; /* Phase: Cross-skill reuse */ 5. $G \leftarrow \text{LinkCanonicalPrototypes}(G)$; /* Stage 2: MotifZip: Contract-Preserving Compression */ 6. $(G_{zip}, M) \leftarrow \text{MotifZip}(G)$; /* Stage 3: PathHydrate: Budgeted Executable Context */ 7. $(C_q, L_q) \leftarrow \text{PathHydrate}(q, p, B, G_{zip}, M)$; /* Stage 4: ReZip: Incremental Library Maintenance */ 8. $U_{run} \leftarrow U$; 9. $Z \leftarrow (G_{zip}, M, B_{res}, \Sigma)$; 10. **for each** new skill or execution trace $u \in U_{run}$ **do** 11. $\quad Z \leftarrow \text{ReZip}(Z, u)$; 12. $(G_{zip}, M, B_{res}, \Sigma) \leftarrow Z$; 13. **return** $C_q, L_q, G_{zip}$;

Robustness and Storage Analysis

SkillZip slashes active storage by 71% while preserving fidelity and scaling gracefully.

SkillZip cuts active storage by $71.0\%$ versus the raw section graph while keeping fallback expansion at $7.2\%$ and downstream inflation at $2.7\%$.

Table 4 shows active storage $18.6\,$MB → $5.4\,$MB (71 % reduction) with low fallback/DI for the full SkillZip pipeline.

When the library expands to $100\,\text{K}$ skills, SkillZip’s top‑1 retrieval accuracy drops only $13.2$ points, far less than SkillDAG’s $30.3$‑point loss.

Table 6 reports Ret@1 $78.3\to65.1$ for SkillZip versus $72.1\to41.8$ for SkillDAG.

Increasing procedural overlap raises the compression ratio to $4.63\times$ while preserving $>99\%$ dependency‑preserve (DPR) and verifier‑reach (VR) rates.

Table 7 shows CR $4.63\times$ at high overlap with DPR $99.1\%$, VR $98.8\%$.

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

**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.

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

**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.

The table compares different representations based on Active MB, Source MB, Fallback (%), and DI (%).

**Table 5.** Robustness under synthetic contract corruption. Noise is the percentage of contract fields removed or replaced. Expansion and fallback are query-level rates, with fallback requiring original-source restoration.

The table compares the performance of SKILLDAG and SkillZip across varying numbers of skills (200 to 100K) using metrics for retrieval accuracy (Ret@1), confusion (Conf.), compression ratio (CR), and latency (Lat.).

**Table 7.** Sensitivity to procedural overlap. Macro support is the mean number of occurrence-specific source subgraphs represented by each active macro; canonical prototypes are not counted.

Scalability and Construction Costs

SkillZip scales, speeds retrieval, and cuts end‑to‑end cost across benchmarks.

SkillZip raises ALFWorld reward by +12.2 points over SkillDAG in repeated‑run evaluation.

Table 13, MiniMax‑M2.7 backbone, ALFWorld benchmark.

Graph + MotifZip construction finishes in 178 s for a 100 K‑skill library.

Read the original paper

Open the simplified reader on Paperglide

Browse all simplified papers