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

> SkillZip compresses agent skill libraries 3.46x by preserving procedural contracts at section level, boosting retrieval up to 12.2 points over SkillDAG.

- **Source:** [arXiv](https://arxiv.org/abs/2608.05604)
- **Published:** 2026-08-14
- **Permalink:** https://picx.dev/p/gEoAIt
- **Whiteboard:** https://picx.dev/p/gEoAIt/image

## Summary

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

## Summary (Overview)

- **SkillZip** is a novel framework for compressing large-scale LLM agent skill libraries by operating at the **section-level granularity** rather than whole-skill packages, enabling more precise retrieval and context hydration within limited context budgets.
- The framework introduces **contract-preserving compression** through four key components: Sec2Graph (section-level graph construction), MotifZip (contract-preserving macro compression), PathHydrate (budgeted executable context hydration), and ReZip (incremental library maintenance).
- SkillZip achieves **3.46× compression ratio** with **99.2% dependency preservation** and **98.7% verifier reachability**, while outperforming the strongest baseline (SkillDAG) by up to **12.2 points** on ALFWorld.
- The system demonstrates **scalability from 200 to 100K skills** with robust retrieval performance, maintaining 65.1 Ret@1 at the largest scale with 248.3 ms online latency.
- SkillZip works as a **plug-and-play procedural-memory layer** across six LLM backbones without backbone-specific fine-tuning, showing consistent improvements on both technical (SkillsBench) and embodied (ALFWorld) benchmarks.

## Introduction and Theoretical Foundation

### Background and Motivation

LLMs increasingly act as agents whose procedural knowledge is stored in reusable skill packages loaded at inference time. As skill libraries grow, a central challenge emerges: **how to expose the smallest sufficient executable context under a limited context budget**. The paper identifies four critical challenges in existing systems:

1. **Reuse-granularity mismatch**: Existing systems use whole skills as retrieval units, but skills contain multiple functional sections (intents, operations, verifiers, outputs) that may be shared across skills.

2. **Contract preservation under compression**: Current compression methods optimize token budgets but preserve textual rather than procedural contracts—a compressed skill can obscure preconditions, guard branches, or verifier hooks.

3. **Persistent executable compression**: Execution graphs are built after retrieval over already-selected skills, so the library itself is not stored as a persistent compressed structure.

4. **Execution-aware maintenance**: Skill libraries evolve, and one-shot compression cannot recognize newly reusable routines or revise risky macros.

### Core Insight

The paper identifies a **unit mismatch**: skills are retrieved as packages, compressed as text, and converted into execution graphs only after retrieval. The solution requires a **contract-bearing procedural unit** that survives retrieval, compression, and execution alike. A compression is **contract-preserving** if it shortens a routine while retaining its interface, execution, and verification aspects.

### Key Definitions

**Section node**: A typed procedural unit:
$$\upsilon = \langle \tau_v, c_v, X_v, Y_v, R_v, G_v, \mathrm{src}_v \rangle$$

where $\tau_v$ is the execution role, $c_v$ is section content, $X_v$ and $Y_v$ are input/output signatures, $R_v$ records resources/tools, $G_v$ records guard/verifier conditions, and $\mathrm{src}_v$ points to source.

The framework uses nine operational roles: **Intent, Trigger, Input, Precondition, Operation, Resource, Failure, Verifier, and Output**.

**Procedural skill graph**: $G = (\mathcal{V}, \mathcal{E}_{dep}, \mathcal{E}_{skill}, \mathcal{E}_{res}, \mathcal{E}_{eq})$ with typed dependency edges ($\mathcal{E}_{dep}$), skill membership edges, resource links, and equivalence edges linking compatible occurrences to canonical prototypes.

**Macro node**: $M_g: I_g \Rightarrow O_g$ compresses a connected section subgraph with boundary inputs $I_g$, outputs $O_g$, and expansion rule $M_g \implies (V_g, E_g, \chi_g)$ where $\chi_g$ is the procedural contract.

## Methodology

### 1. Sec2Graph: Building Procedural Subgraphs

Converts whole skill packages into source-grounded procedural subgraphs:

- **Section grounding**: Segments packages using headings, lists, code blocks, warnings, and tool references as boundary cues
- **Contract extraction**: Extracts typed I/O $(X_v, Y_v)$ and resources $R_v$ for interface; guards and verifier conditions in $G_v$
- **Procedural subgraph construction**: Connects sections with typed edges (weak-order, dependency, verifier, repair edges)
- **Cross-skill reuse**: Links compatible sections to shared canonical prototypes while preserving occurrence identity

### 2. MotifZip: Contract-Preserving Compression

Mines recurring section-level motifs and promotes them to macro nodes only when contracts are preserved:

**Typed candidate generation**:
$$\mathcal{C} = \text{GrowMotifs}(\text{BucketBySignature}(\mathcal{G}), \mathcal{G})$$

**Graph grammar rule**:
$$M_g[I_g, O_g] \Rightarrow (V_g, E_g, \pi_g, \chi_g)$$

**Compression gain scoring**:
$$\Delta(g) = \text{freq}(g)L(g) - L(M_g) - L(\text{rule}_g) + \alpha\text{Reuse}(g) - \lambda\text{Cut}(g) - \mu\text{Risk}(g)$$

A motif is accepted only if: (1) interface is stable across occurrences, (2) execution is dependency-closed, (3) verification remains reachable.

**Key theoretical guarantee (Proposition 1)**: Compositional structural lifting—if a raw procedural subgraph $P$ contains all or none of the internal nodes for each occurrence, then $\xi_\Omega(\kappa_\Omega(P)) \cong P$ up to auxiliary prototype links, preserving typed external dependencies and operation-to-verifier reachability.

### 3. PathHydrate: Budgeted Executable Context

Builds compact, dependency-closed procedural subgraphs for queries:

**Task anchoring**: Converts queries into structured objects:
$$z_q = (g_q, O_q, \Gamma_q, I_q, D_q, \{d_i\})$$

**Dual-level seed fusion**: Combines section-level and skill-level retrieval:
$$s(v, d_i, q) = \max\{\cos(\mathbf{e}(d_i), \mathbf{e}(v)), \cos(\mathbf{e}(q), \mathbf{e}(v))\}$$

Skills are fused via reciprocal-rank fusion:
$$\text{RRF}(\sigma) = \sum_{r \in \mathcal{R}_{rank}} \frac{1}{k + \text{rank}_r(\sigma)}$$

**Constrained subgraph search**:
$$P_q^* = \arg\min_{P \subseteq \mathcal{G}_{zip}} \eta T(P) + \beta|P| + \gamma E(P) - \delta\text{Match}(P, q)$$

subject to anchor coverage, dependency closure, verifier reachability, and budget $T(P) \leq B$.

**Progressive hydration**: Macros rendered at lowest sufficient level: name, contract, outline, or full source.

### 4. ReZip: Incremental Library Maintenance

Updates the compressed library as new skills and execution traces arrive:

$$\mathcal{Z}_{t+1} = \text{ReZip}(\mathcal{Z}_t, u_t)$$

**Macro promotion condition**:
$$\text{supp}_t(r) \geq m, \quad \Delta(r) > 0, \quad \text{Valid}_\chi(r) = 1$$

**Execution risk scoring**:
$$\rho_t(M) = \lambda_e \frac{n_{\text{exp}}(M)}{n_{\text{use}}(M)} + \lambda_v \frac{n_{\text{fail}}(M)}{n_{\text{use}}(M)} + \lambda_d \frac{c_{\text{repair}}(M)}{n_{\text{use}}(M)}$$

## Empirical Validation / Results

### Main Results (RQ1)

| Backbone | Method | SkillsBench R↑ | ALFWorld R↑ |
|----------|--------|---------------|-------------|
| MiniMax-M2.7 | Vanilla Skills | 17.2 | 47.1 |
| MiniMax-M2.7 | Vector Skills | 10.4 | 50.7 |
| MiniMax-M2.7 | GoS | 18.7 | 54.3 |
| MiniMax-M2.7 | SkillDAG | 27.3 | 67.1 |
| **MiniMax-M2.7** | **SkillZip** | **33.3** | **79.3** |
| gpt-5.2-codex | Vanilla Skills | 27.4 | 89.3 |
| gpt-5.2-codex | Vector Skills | 21.5 | 92.9 |
| gpt-5.2-codex | GoS | 34.4 | 93.6 |
| gpt-5.2-codex | SkillDAG | 36.8 | 93.6 |
| **gpt-5.2-codex** | **SkillZip** | **43.0** | **96.4** |

SkillZip improves over SkillDAG by **6.0–12.2 points** on SkillsBench and **2.8–12.2 points** on ALFWorld, with the largest gains on the weaker backbone where there is more room for improvement.

### Compression and Structural Fidelity (RQ3)

| Representation | CR↑ | Tok↓ | DPR↑ | VR↑ | Recover.↓ | R↑ |
|----------------|-----|------|------|-----|-----------|-----|
| Raw section graph | 1.00× | 6,716 | 100.0 | 100.0 | 0.0 | 31.0 |
| Exact-text dedup. | 1.43× | 4,697 | 98.6 | 98.1 | 5.2 | 31.2 |
| Text compression | 3.46× | 1,941 | 65.0 | 60.0 | 45.0 | 25.5 |
| Generic graph grammar | 2.91× | 2,308 | 93.4 | 90.8 | 22.7 | 29.4 |
| SkillZip w/o checks | 3.78× | 1,777 | 88.9 | 84.6 | 31.5 | 27.8 |
| **SkillZip** | **3.46×** | **1,941** | **99.2** | **98.7** | **14.8** | **33.3** |

Key findings:
- Text compression achieves similar compression but **destroys executable structure** (DPR: 65.0, VR: 60.0)
- Removing contract checks makes compression more compact (3.78×) but **harms execution safety**
- SkillZip preserves near-complete structural fidelity (DPR: 99.2, VR: 98.7) while achieving 3.46× compression

### Ablation Study (RQ4)

| Component | Variant | R↑ | Ret@1↑ | Tok↓ | DPR↑ | VR↑ |
|-----------|---------|-----|--------|------|------|-----|
| Full | SkillZip | 33.3 | 73.6 | 1,941 | 99.2 | 98.7 |
| Unit | w/o section-level nodes | 27.9 | 66.7 | 3,103 | - | - |
| Compression | w/o MotifZip | 31.0 | 71.8 | 2,967 | 100.0 | 100.0 |
| Compression | w/o dependency closure | 28.6 | 72.1 | 1,653 | 82.3 | 92.6 |
| Compression | w/o verifier constraint | 29.1 | 72.8 | 1,668 | 94.9 | 76.4 |
| Hydration | w/o global section rescue | 30.4 | 68.2 | 1,812 | 96.5 | 96.8 |
| Hydration | w/o adaptive hydration | 31.5 | 73.2 | 2,587 | 99.2 | 98.7 |

Key findings:
- **Section-level nodes are critical**: removing them causes the largest drop (Ret@1: -6.9, reward: -5.4, context: +59.9%)
- **Contract checks matter**: removing dependency closure drops DPR to 82.3; removing verifier constraints drops VR to 76.4
- **Adaptive hydration saves 33.3% tokens** without harming structural fidelity

### Additional Results

- **Scalability**: Ret@1 advantage over SkillDAG widens from 6.2 (200 skills) to 23.3 (100K skills); at 100K skills, SkillZip retains 65.1 Ret@1 with 248.3 ms latency
- **Contract extraction quality**: 91.6 macro-F1 and 84.6 exact match against human annotations
- **Efficiency gains**: 47.0% reduction in cumulative prompt processing, 21.7% fewer tool calls, 21.1% faster end-to-end task time vs. SkillDAG

## Theoretical and Practical Implications

### Theoretical Contributions

1. **Contract-preserving compression**: Introduces a formal notion of compression that preserves procedural contracts (interface, execution, verification) rather than just textual similarity, with a proven compositional lifting property (Proposition 1) guaranteeing reversible macro expansion.

2. **Section-level procedural memory**: Establishes that skills are not atomic units but collections of typed, contract-bearing sections that can be independently reused across skills—a fundamental shift from whole-skill retrieval.

3. **Unified representation**: Shows that retrieval, compression, and execution should operate on the same unit (contract-bearing section subgraphs), resolving the unit mismatch in existing pipelines.

### Practical Implications

1. **Scalable skill libraries**: Enables efficient skill reuse in libraries ranging from hundreds to hundreds of thousands of skills, with retrieval precision that improves relative to baselines as libraries grow.

2. **Context efficiency**: Reduces rendered context by 72.1% compared to top-5 whole-skill loading while maintaining or improving task performance, critical for LLM context budget constraints.

3. **Safe compression**: Provides a principled approach to compression that maintains executable structure—shorter context does not come at the cost of dropped verifiers or hidden dependencies.

4. **Maintainable systems**: The ReZip component enables continuous library evolution, promoting new reusable routines and retiring risky macros based on execution evidence.

## Conclusion

SkillZip presents a comprehensive solution to the challenge of scalable agent skill libraries by fundamentally changing the unit of procedural reuse from whole skill packages to contract-bearing section-level graphs. The framework's four components work together: Sec2Graph exposes internal skill structure, MotifZip compresses only contract-valid recurring motifs, PathHydrate builds minimal executable contexts, and ReZip maintains the compressed library as skills evolve.

The empirical results demonstrate that **execution-aware compression outperforms both whole-skill retrieval and text-only compression** across multiple LLM backbones and task domains. The 3.46× compression ratio with near-perfect dependency preservation (99.2%) and verifier reachability (98.7%) shows that significant context savings are achievable without sacrificing executable structure.

**Future directions** suggested by this work include extending the framework to handle more complex procedural contracts (e.g., multi-agent coordination), investigating semantic rather than structural equivalence guarantees, and exploring how execution evidence can be more richly incorporated into macro revision decisions. The framework's plug-and-play nature across LLM backbones also opens possibilities for integration with other agent architectures and skill-acquisition systems.

---

_Markdown view of https://picx.dev/p/gEoAIt, served by PicX — AI-generated visual whiteboard summaries of research papers._