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:

# 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:

# 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:

## 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 loading any skill file:
1. Does the current task need it? (yes → load it, no → skip)
2. Has it already been loaded this session? (yes → skip, no → load once)

See AGENTS.md.template for the full recommended AGENTS.md skills section.

Step 3: Use the Context Optimizer (Optional)

The included context_optimizer.py analyzes your task description and recommends which skills to load:

python3 context_optimizer.py recommend "Write a Python script to push to S3"
# Output:
# Recommended skills to load:
#   - skills/python/SKILL.md  (confidence: high — Python task)
#   - skills/aws/SKILL.md     (confidence: high — S3 mentioned)
#   - skills/git/SKILL.md     (confidence: low  — skip unless pushing to GitHub)

Step 4: Apply to Memory Files Too

The same pattern works for memory and context files:

## Memory Loading (AGENTS.md)