openclaw-skill-lazy-loader

# OpenClaw Skill Lazy Loader

Stop loading every skill file at session start. Load what you need, when you need it — and cut your token usage by 40–70%.

## The Problem

Most OpenClaw agents load their entire skill library at startup:

```markdown
# AGENTS.md (naive approach)
Read ALL of these before starting:
- skills/python/SKILL.md
- skills/git/SKILL.md
- skills/docker/SKILL.md
- skills/aws/SKILL.md
- skills/browser/SKILL.md
... (20 more)
```

Each session burns **3,000–15,000 tokens** just loading context that may never be used. At scale, this is your biggest cost.

## The Solution: Lazy Loading

Instead of loading skills upfront, agents check a **SKILLS catalog** (a lightweight index) and load individual skill files only when a task requires them.

**Before:** Load 20 skill files = ~12,000 tokens/session
**After:** Load catalog (300 tokens) + 1–2 relevant skills (~800 tokens) = **~1,100 tokens/session**

That's an **89% reduction** on context loading alone.

---

## Implementation Guide

### Step 1: Create Your SKILLS Catalog

Create `SKILLS.md` in your agent workspace — a lightweight index of all available skills:

```markdown
# Available Skills

| Skill | File | Use When |
|-------|------|----------|
| Python | skills/python/SKILL.md | Writing/debugging Python code |
| Git | skills/git/SKILL.md | Git operations, PRs, branches |
| Docker | skills/docker/SKILL.md | Containers, images, compose |
| Browser | skills/browser/SKILL.md | Web scraping, UI automation |
| AWS | skills/aws/SKILL.md | Cloud deployments, S3, Lambda |
```

This catalog is the ONLY file loaded at session start. ~200–400 tokens instead of 10,000+.

See `SKILLS.md.template` for a complete starter template.

### Step 2: Update Your AGENTS.md

Replace bulk loading with the catalog pattern:

```markdown
## Skills

At session start: Read SKILLS.md (the index only).
When a task needs a skill: Read the specific SKILL.md for that skill.
Never load all skills upfront.

### Loading Decision
Before load...

# OpenClaw Skill Lazy Loader

> Stop loading every skill file at session start. Cut context loading costs by 40–93%.

[![ClawHub](https://img.shields.io/badge/ClawHub-Asif2BD%2Fopenclaw--skill--lazy--loader-green)](https://clawhub.ai/Asif2BD/openclaw-skill-lazy-loader)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.0.0-brightgreen)](CHANGELOG.md)

## What It Does

Most OpenClaw agents eagerly load all their skill files at session start — burning thousands of tokens on context that may never be used. This skill teaches you (and your agents) how to fix that.

**The pattern:** Use a lightweight SKILLS catalog (~300 tokens) at startup. Load individual skill files only when a task actually needs them.

**Result:** 40–93% reduction in context loading costs, depending on your skill library size.

## Install

```bash
clawhub install openclaw-skill-lazy-loader
```

## Quick Start

```bash
# 1. Copy the SKILLS catalog template to your agent workspace
cp ~/.openclaw/skills/openclaw-skill-lazy-loader/SKILLS.md.template ~/my-agent/SKILLS.md

# 2. Edit it — fill in your actual skills
nano ~/my-agent/SKILLS.md

# 3. Update your AGENTS.md to use the lazy loading pattern
# (copy the relevant section from AGENTS.md.template)

# 4. Test the optimizer
python3 ~/.openclaw/skills/openclaw-skill-lazy-loader/context_optimizer.py recommend "your task"
```

## Token Savings

| Skills in library | Before | After | Savings |
|-------------------|--------|-------|---------|
| 5 skills | ~3,000 tok | ~600 tok | **80%** |
| 10 skills | ~6,500 tok | ~750 tok | **88%** |
| 20 skills | ~13,000 tok | ~900 tok | **93%** |

## What's Included

- **`SKILL.md`** — Full implementation guide
- **`SKILLS.md.template`** — Ready-to-use skill catalog starter
- **`AGENTS.md.template`** — AGENTS.md lazy loading section to paste in
- **`context_optimizer.py`** — CLI tool: recommends which skills to load per task

## Pairs With

→ [O...