Skill: asif2bd/openclaw-skill-lazy-loader (version 1.0.0)

--- name: openclaw-skill-lazy-loader description: Dramatically reduce per-session token usage by loading skills and context files only when needed — not at session start. Includes the SKILLS catalog pattern, AGENTS.md lazy loading strategy, and a Python helper that recommends exactly which files to load for any given task. Compatible with all OpenClaw agents. Works alongside Token Optimizer. version: 1.0.0 homepage: https://github.com/Asif2BD/openclaw-skill-lazy-loader source: https://github.com/Asif2BD/openclaw-skill-lazy-loader author: Asif2BD license: Apache 2.0 security: verified: true auditor: Oracle (Matrix Zion) audit_date: 2026-02-28 scripts_no_network: true scripts_no_code_execution: true scripts_no_subprocess: true scripts_data_local_only: true --- # 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 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: ```bash 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: ```markdown ## Memory Loading (AGENTS.md) At session start: Read MEMORY.md (summary only). Load daily files (memory/YYYY-MM-DD.md) only when: - User asks about past work - Task references a specific date or project - Debugging requires historical context ``` --- ## Token Savings Calculator | Scenario | Before | After | Savings | |----------|--------|-------|---------| | 5 skills loaded | ~3,000 tokens | ~600 tokens | 80% | | 10 skills loaded | ~6,500 tokens | ~750 tokens | 88% | | 20 skills loaded | ~13,000 tokens | ~900 tokens | 93% | | +Memory files (5) | +4,000 tokens | +400 tokens | 90% | *Estimates based on average SKILL.md size of ~600 tokens. Catalog averages ~150 tokens.* --- ## Integration with Token Optimizer This skill pairs directly with [OpenClaw Token Optimizer](https://clawhub.ai/Asif2BD/openclaw-token-optimizer). Lazy loading handles **context loading costs**; Token Optimizer handles **model routing, heartbeat budgeting, and runtime costs**. Together they cover the full token lifecycle. Install both: ```bash clawhub install openclaw-skill-lazy-loader clawhub install openclaw-token-optimizer ``` --- ## Files in This Skill | File | Purpose | |------|---------| | `SKILL.md` | This guide | | `SKILLS.md.template` | Starter SKILLS catalog template | | `AGENTS.md.template` | Lazy loading AGENTS.md section | | `context_optimizer.py` | CLI helper — recommends skills to load per task | | `README.md` | ClawHub listing description | | `SECURITY.md` | Security audit and script disclosure | | `.clawhubsafe` | File integrity manifest | --- ## Quick Start (5 minutes) ```bash # 1. Install clawhub install openclaw-skill-lazy-loader # 2. Copy templates to your agent workspace cp ~/.openclaw/skills/openclaw-skill-lazy-loader/SKILLS.md.template ~/my-agent/SKILLS.md cp ~/.openclaw/skills/openclaw-skill-lazy-loader/AGENTS.md.template ~/my-agent/AGENTS.lazy.md # 3. Edit SKILLS.md — fill in your actual skills # 4. Merge AGENTS.lazy.md into your AGENTS.md # 5. Test with context_optimizer.py python3 ~/.openclaw/skills/openclaw-skill-lazy-loader/context_optimizer.py recommend "your next task" ``` --- *By M Asif Rahman (@Asif2BD) · Apache 2.0 · https://clawhub.ai/Asif2BD/openclaw-skill-lazy-loader*

path: SKILLS.md.template
content: # SKILLS — Available Skills Catalog

<!--
This is your agent's skill index. Load this file at session start (it's lightweight).
Load individual SKILL.md files only when a task actually needs them.
Part of: OpenClaw Skill Lazy Loader (clawhub install openclaw-skill-lazy-loader)
-->

## How to Use This Catalog

At session start: Read this file only (~300 tokens).
When you need a skill: Read the specific SKILL.md listed below.
Never load all skills at once — load on demand.

**Decision rule:** Before loading a skill file, ask: "Does my current task require this?" If no → skip.

---

## Installed Skills

| Skill | File | Use When | Size |
|-------|------|----------|------|
| Python | `skills/python/SKILL.md` | Writing, debugging, or reviewing Python code | ~600 tok |
| JavaScript / TypeScript | `skills/js/SKILL.md` | Frontend/backend JS, React, Node.js tasks | ~700 tok |
| Git | `skills/git/SKILL.md` | Git commands, PRs, branches, merges | ~400 tok |
| Docker | `skills/docker/SKILL.md` | Containers, images, docker-compose, builds | ~550 tok |
| Browser Automation | `skills/browser/SKILL.md` | Web scraping, UI testing, Playwright | ~800 tok |
| AWS | `skills/aws/SKILL.md` | S3, Lambda, EC2, CloudFormation | ~900 tok |
| SQL / Databases | `skills/sql/SKILL.md` | Queries, schema design, migrations | ~500 tok |
| API Design | `skills/api/SKILL.md` | REST APIs, OpenAPI specs, authentication | ~600 tok |
| Linux / Shell | `skills/shell/SKILL.md` | Bash scripts, system administration | ~450 tok |
| Code Review | `skills/review/SKILL.md` | PR reviews, code quality checks | ~350 tok |

<!--
Add your own skills below. Format:
| Name | `path/to/SKILL.md` | When to load | ~NNN tok |
-->

---

## Memory Files (Lazy Load These Too)

| File | Load When |
|------|-----------|
| `MEMORY.md` | Always (load at start — it's a summary) |
| `memory/YYYY-MM-DD.md` | User asks about that specific day's work |
| `memory/projects/*.md` | Task involves that specific project |

---

## Loading Examples

**Task: "Fix a Python bug in the authentication module"**
→ Load: `skills/python/SKILL.md`
→ Skip: git, docker, aws, browser (not needed)

**Task: "Review this PR and push the fix"**
→ Load: `skills/review/SKILL.md`, `skills/git/SKILL.md`
→ Skip: everything else

**Task: "Build a Docker image and push to ECR"**
→ Load: `skills/docker/SKILL.md`, `skills/aws/SKILL.md`
→ Skip: python, browser, sql

---

*Generated by OpenClaw Skill Lazy Loader v1.0.0*
*Edit this file to match your actual installed skills.*


path: AGENTS.md.template
content: ## Skills (Lazy Loading)

<!--
Paste this section into your agent's AGENTS.md to enable lazy skill loading.
Part of: OpenClaw Skill Lazy Loader (clawhub install openclaw-skill-lazy-loader)
-->

### Skill Loading Strategy

**At session start:** Read `SKILLS.md` only (the catalog index — lightweight, ~300 tokens).

**Do NOT read all skill files at startup.** Load individual skills on demand.

**When to load a skill file:**
- You're about to perform a task that requires it
- You're unsure how to do something and the skill file would help
- You haven't loaded it yet this session

**When NOT to load a skill file:**
- The current task doesn't need it
- You already loaded it earlier this session
- You're doing a simple conversational task

### Loading Decision Process

Before starting any task:
1. Check: Does this task need specialized knowledge from a skill?
2. If yes: Look up the skill in `SKILLS.md` → load just that file
3. If no: Proceed without loading anything extra

**Example internal reasoning:**
```
Task: "Write a Python function to parse JSON"
→ Check SKILLS.md → Python skill available at skills/python/SKILL.md
→ Load skills/python/SKILL.md
→ Proceed with task
```

```
Task: "What time is it in Tokyo?"
→ Check: Need a skill? No — general knowledge task
→ Load nothing
→ Proceed with answer
```

### Memory Files

**At session start:** Read `MEMORY.md` only (summary — load always).

**Load daily memory files (`memory/YYYY-MM-DD.md`) only when:**
- User asks about work from a specific date
- Task involves a project that may have historical context
- Debugging requires understanding what changed recently

**Do NOT load all daily memory files at startup** — they add up fast.

### Session-Level Tracking (Optional)

If your agent supports tool use, track what's been loaded this session to avoid double-loading:

```
Loaded this session:
- skills/python/SKILL.md ✓
- memory/2026-02-27.md ✓
```

Only load each file once per session.

---

<!-- Token savings with this pattern: 40–93% reduction on context loading -->
<!-- For more: clawhub install openclaw-skill-lazy-loader -->


path: context_optimizer.py
content: #!/usr/bin/env python3
"""
context_optimizer.py — OpenClaw Skill Lazy Loader
Recommends which skill files to load for a given task description.

No network requests. No subprocess calls. No system modifications.
Runs entirely on local data — reads SKILLS.md in the current directory.

Usage:
    python3 context_optimizer.py recommend "Write a Python script to upload to S3"
    python3 context_optimizer.py list
    python3 context_optimizer.py estimate "your task description"

Part of: OpenClaw Skill Lazy Loader v1.0.0
Author: M Asif Rahman (@Asif2BD) | Apache 2.0
"""

import sys
import os
import re
from pathlib import Path

# ---------------------------------------------------------------------------
# Keyword → skill mapping (extend this to match your SKILLS.md catalog)
# ---------------------------------------------------------------------------
SKILL_KEYWORDS: dict[str, list[str]] = {
    "python": ["python", "py", "pip", "pytest", "django", "flask", "fastapi", "pandas", "numpy"],
    "javascript": ["javascript", "typescript", "js", "ts", "node", "react", "vue", "angular", "npm", "yarn"],
    "git": ["git", "commit", "branch", "pull request", "pr", "merge", "rebase", "push", "clone"],
    "docker": ["docker", "container", "image", "dockerfile", "compose", "kubernetes", "k8s", "helm"],
    "browser": ["browser", "scrape", "playwright", "selenium", "puppeteer", "webpage", "web automation", "ui test"],
    "aws": ["aws", "s3", "lambda", "ec2", "cloudformation", "iam", "dynamodb", "rds", "ecr", "ecs"],
    "sql": ["sql", "database", "postgres", "mysql", "sqlite", "query", "schema", "migration", "orm"],
    "api": ["api", "rest", "endpoint", "openapi", "swagger", "authentication", "oauth", "jwt", "webhook"],
    "shell": ["bash", "shell", "linux", "cron", "systemd", "chmod", "grep", "awk", "sed", "ssh"],
    "review": ["review", "code review", "pr review", "pull request review", "quality", "linting"],
}

CONFIDENCE_COLORS = {
    "high":   "✅ high  ",
    "medium": "⚡ medium",
    "low":    "💭 low   ",
}


def load_skills_catalog(catalog_path: str = "SKILLS.md") -> dict[str, str]:
    """Parse SKILLS.md to extract skill → file path mapping."""
    skills = {}
    path = Path(catalog_path)
    if not path.exists():
        return skills

    for line in path.read_text().splitlines():
        # Match table rows: | Name | `path/to/SKILL.md` | ... |
        m = re.match(r"\|\s*([^|]+?)\s*\|\s*`([^`]+)`\s*\|", line)
        if m:
            name = m.group(1).strip().lower()
            file_path = m.group(2).strip()
            skills[name] = file_path
    return skills


def score_task(task: str) -> dict[str, str]:
    """Score a task description against skill keywords, return skill → confidence."""
    task_lower = task.lower()
    scores: dict[str, int] = {}

    for skill, keywords in SKILL_KEYWORDS.items():
        hits = sum(1 for kw in keywords if kw in task_lower)
        if hits > 0:
            scores[skill] = hits

    if not scores:
        return {}

    max_hits = max(scores.values())
    result = {}
    for skill, hits in sorted(scores.items(), key=lambda x: -x[1]):
        if hits == max_hits:
            result[skill] = "high"
        elif hits >= max_hits * 0.5:
            result[skill] = "medium"
        else:
            result[skill] = "low"
    return result


def cmd_recommend(task: str) -> None:
    """Recommend skills to load for a given task."""
    if not task.strip():
        print("Usage: context_optimizer.py recommend \"your task description\"")
        sys.exit(1)

    catalog = load_skills_catalog()
    scores = score_task(task)

    print(f"\nTask: \"{task}\"")
    print("-" * 60)

    if not scores:
        print("No specific skills detected. Proceed without loading any skill files.")
        print("\nEst. token cost: ~0 (beyond base catalog)\n")
        return

    print("Recommended skills to load:\n")
    total_tokens = 0
    SKILL_SIZES = {
        "python": 600, "javascript": 700, "git": 400, "docker": 550,
        "browser": 800, "aws": 900, "sql": 500, "api": 600,
        "shell": 450, "review": 350,
    }
    load_these = []
    skip_these = []

    for skill, confidence in scores.items():
        file_path = catalog.get(skill, f"skills/{skill}/SKILL.md")
        size = SKILL_SIZES.get(skill, 500)
        badge = CONFIDENCE_COLORS.get(confidence, confidence)

        if confidence in ("high", "medium"):
            load_these.append((skill, file_path, badge, size))
            total_tokens += size
        else:
            skip_these.append((skill, file_path, badge))

    for skill, path, badge, size in load_these:
        print(f"  LOAD  [{badge}] {path}  (~{size} tok)")

    if skip_these:
        print()
        for skill, path, badge in skip_these:
            print(f"  SKIP  [{badge}] {path}  (low relevance)")

    print(f"\nEst. token cost: ~{total_tokens:,} tokens (context loading)")
    if total_tokens == 0:
        print("No files to load — proceed directly.")
    print()


def cmd_list() -> None:
    """List all skills in the catalog."""
    catalog = load_skills_catalog()
    if not catalog:
        print("No SKILLS.md found in current directory.")
        print("Copy SKILLS.md.template → SKILLS.md and fill in your skills.")
        return

    print(f"\nAvailable skills ({len(catalog)} total):\n")
    for name, path in catalog.items():
        print(f"  {name:<20} → {path}")
    print()


def cmd_estimate(task: str) -> None:
    """Estimate token cost with vs without lazy loading."""
    catalog = load_skills_catalog()
    total_skills = max(len(catalog), 5)  # assume at least 5 if catalog missing

    avg_skill_size = 600
    catalog_size = 300
    recommended = len(score_task(task))

    cost_naive = total_skills * avg_skill_size
    cost_lazy = catalog_size + min(recommended, 3) * avg_skill_size

    savings = max(0, cost_naive - cost_lazy)
    pct = int(savings / cost_naive * 100) if cost_naive > 0 else 0

    print(f"\nToken Estimate for: \"{task}\"")
    print("-" * 60)
    print(f"  Without lazy loading: ~{cost_naive:,} tokens ({total_skills} skills loaded)")
    print(f"  With lazy loading:    ~{cost_lazy:,} tokens (catalog + {min(recommended,3)} relevant skills)")
    print(f"  Savings:              ~{savings:,} tokens ({pct}% reduction)\n")


def print_help() -> None:
    print("""
OpenClaw Skill Lazy Loader — context_optimizer.py

Commands:
  recommend "<task>"   Recommend which skills to load for a task
  list                 List all skills in your SKILLS.md catalog
  estimate "<task>"    Show token cost comparison (lazy vs naive)

Examples:
  python3 context_optimizer.py recommend "Write a Python function to parse JSON"
  python3 context_optimizer.py recommend "Build a Docker image and push to ECR"
  python3 context_optimizer.py list
  python3 context_optimizer.py estimate "Review this pull request"

No network access. No file writes. Local data only.
""")


def main() -> None:
    args = sys.argv[1:]
    if not args or args[0] in ("-h", "--help", "help"):
        print_help()
        return

    cmd = args[0]
    task = " ".join(args[1:]) if len(args) > 1 else ""

    if cmd == "recommend":
        cmd_recommend(task)
    elif cmd == "list":
        cmd_list()
    elif cmd == "estimate":
        cmd_estimate(task)
    else:
        print(f"Unknown command: {cmd}")
        print_help()
        sys.exit(1)


if __name__ == "__main__":
    main()


path: README.md
content: # 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

→ [OpenClaw Token Optimizer](https://clawhub.ai/Asif2BD/openclaw-token-optimizer) — handles model routing and runtime costs. Together they cover the entire token lifecycle.

## Author

**M Asif Rahman** ([@Asif2BD](https://github.com/Asif2BD)) — Matrix Zion AI team  
Apache 2.0 · [GitHub](https://github.com/Asif2BD/openclaw-skill-lazy-loader) · [ClawHub](https://clawhub.ai/Asif2BD/openclaw-skill-lazy-loader)


path: SECURITY.md
content: # Security Disclosure — OpenClaw Skill Lazy Loader v1.0.0

**Auditor:** Oracle (Matrix Zion)
**Audit Date:** 2026-02-28
**Verdict:** ✅ Clean — no network access, no code execution, no system modifications

---

## File-by-File Breakdown

### SKILL.md
- Type: Markdown documentation
- Network access: None
- File writes: None
- Verdict: ✅ Safe — read-only text

### SKILLS.md.template
- Type: Markdown template
- Network access: None
- File writes: None
- Verdict: ✅ Safe — read-only text

### AGENTS.md.template
- Type: Markdown template
- Network access: None
- File writes: None
- Verdict: ✅ Safe — read-only text

### README.md
- Type: Markdown documentation
- Network access: None
- File writes: None
- Verdict: ✅ Safe — read-only text

### context_optimizer.py

**What it does:**
Reads a task description from the command line. Scores it against a local keyword table. Optionally reads `SKILLS.md` from the current directory. Prints recommendations to stdout.

**What it does NOT do:**
- No network requests of any kind
- No subprocess calls
- No file writes (read-only access to SKILLS.md if present)
- No environment variable modifications
- No system configuration changes
- No imports beyond Python stdlib (`sys`, `os`, `re`, `pathlib`)

**Verification (one-liner):**
```bash
grep -E "import (requests|urllib|http|socket|subprocess|os\.system)" context_optimizer.py
# Should return nothing
```

**Full source:** https://github.com/Asif2BD/openclaw-skill-lazy-loader/blob/main/context_optimizer.py

**Verdict:** ✅ Safe — pure Python stdlib, local data only, read-only

---

## What This Skill Cannot Do

- Cannot make network requests
- Cannot modify any system files
- Cannot install packages
- Cannot spawn processes
- Cannot read files outside the current directory (SKILLS.md only)
- Cannot write any files

---

## Provenance & Source

- **GitHub:** https://github.com/Asif2BD/openclaw-skill-lazy-loader
- **ClawHub:** https://clawhub.ai/Asif2BD/openclaw-skill-lazy-loader
- **Author:** M Asif Rahman (@Asif2BD)
- **License:** Apache 2.0

Verify file integrity:
```bash
sha256sum SKILL.md SKILLS.md.template AGENTS.md.template context_optimizer.py README.md SECURITY.md
# Compare against hashes in .clawhubsafe
```


path: .clawhubsafe
content: # OpenClaw Skill Lazy Loader — File Integrity Manifest
# Version: 1.0.0
# Generated: 2026-02-28
# Algorithm: SHA256

155d4f2ffbcb8dcd0dc13b91cf79f1d3005e8b5435550bc77424d9a3f4185a54  SKILL.md
cff434938c0836c5bc7efa2b0dcfb1ec32793c1f975afdef64aea8a759226737  SKILLS.md.template
0ca5852bb849ed2faf60649b3669a8a78c798fb74f1ef8e3082b2ad712d9dd44  AGENTS.md.template
29f50fc3153aa9d5572e936029e09400809fde5e8fe5863f58ce06f9a0562f04  context_optimizer.py
baabd4866f11c55f0c0787467558ecf19aaca0350ae8f1efe8b29d192e592b28  README.md
003382aa2e22acb14aa171f993ddaea80e457e852d47a00e0e52acd3c0a7c55b  SECURITY.md


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)