What is progressive disclosure in OpenClaw skills?

Progressive disclosure means only a skill's name and description are loaded into the agent's context window by default. The full skill body — all its instructions and steps — is only loaded when the agent determines it needs that specific skill. This makes skills far more token-efficient than CLAUDE.md files, which load their full contents on every single message turn.

Should I use a CLAUDE.md file with OpenClaw?

Only if you have truly proprietary information that must be present in every single agent interaction. For 95% of users, CLAUDE.md files are unnecessary — the model already knows about common frameworks, tools, and workflows. A 1,000-line CLAUDE.md file costs roughly 7,000 tokens per message turn. Skills with progressive disclosure cost only the token length of a name and one-line description until invoked.

How do I build an OpenClaw skill correctly?

Identify the recurring workflow, run it step by step with your agent in a live session, correct it at each stage, and repeat until you get a clean end-to-end run. Then tell the agent: 'Review what you just did and create a skill for it.' The agent writes the skill with actual context from a working run — not generic guesses. Never write skills cold or download third-party skills without auditing them.

Published: 2026-04-08
Explainer & perspective

OpenClaw Skills Explained: Why 95% of Agents Don't Need a CLAUDE.md File

Chapters / key moments (click to jump — plays here on the page)

A developer and OpenClaw power user (guest on the Greg Isenberg podcast) breaks down how OpenClaw agent context actually works, arguing that most users waste tokens with bloated CLAUDE.md files when skills with progressive disclosure are far more efficient. He explains why you should always build skills by walking through workflows with your agent live first — and why downloading third-party skills is both a security risk and a context mismatch problem.

Source video

"How AI agents & Claude skills work (Clearly Explained)" by Greg Isenberg — Watch on YouTube →

Key Takeaways

Skills use progressive disclosure — only the skill's name and description are loaded into the agent's context window. The full skill instructions only load when the agent decides it needs that specific skill. This is drastically more token-efficient than putting everything in CLAUDE.md.
CLAUDE.md files add their full token count to every single turn — at 1,000 lines, that's roughly 7,000 tokens per message. This is only justified for truly proprietary company workflows that must be referenced on every single action.
Build skills by doing the workflow WITH the agent first — identify the task, run it live in a session, correct the agent step by step until you get a clean successful run, then ask it to write the skill from that working context. Never write or download skills cold.
Never download third-party skills blindly — beyond the security risk of running untrusted code, downloaded skills lack the context of your specific workflows, model behavior, and edge cases. They will fail in non-obvious ways.
The models are already excellent — Claude Opus 4.6 and GPT 5.4 are both capable of high-quality work. The bottleneck is almost always context design: what you give the agent to work with, not the model's raw ability.

How Skills Progressive Disclosure Works

A skill file has three parts: a name, a description, and a body of instructions. When you run an OpenClaw agent, only the name and description of each skill enter the context window — not the full body. When you tell the agent to do something that matches a skill's description, the agent loads the full skill body and follows its steps. This means you can have dozens of skills registered without paying their token cost unless the agent actually invokes them.

Contrast this with CLAUDE.md: its full contents are added to the context on every single message exchange. For large files, this becomes a significant cost multiplier and can push the agent toward its context limit faster in long sessions.

The Right Way to Build a Skill

Identify a recurring workflow you do with your agent.
Run the workflow step by step in a live session, correcting the agent at each stage.
Repeat until you have a clean, successful end-to-end run.
Tell the agent: "Review what you just did and create a skill for it."
The agent writes the skill with real context from an actual working run — not generic guesses.

Related on OpenClawDatabase

OpenClaw Skills Guide — how to write, install, and manage skills
OpenClaw Skills Database — curated registry of community skills
OpenClaw Email Integration — set up your agent's own inbox, like the sponsor-filter workflow described in this video
OpenClaw Security Hardening — why third-party skill safety matters
Claude Code Workflow: IdeaBrowser MCP + Paper UI — a complementary look at Claude Code in a real product workflow

What you can actually set up from this

Extracted from the video's own transcript — the specifics the original summary left out.

Configuration shown

The shape of a skill file — and why it is cheap

name: <short name>
description: <when the agent should reach for this>
---
<the actual instructions — the bulk of the file>

# Only `name` and `description` sit in context.
# The body loads only once a task matches. This is progressive disclosure.

Template shown in the video. Adapt to your project — do not copy verbatim without reviewing each line.

Reproducible steps

Know what is actually filling your context window
Six things are assembled before the model does anything: the provider's own system prompt, your agent.md / CLAUDE.md, your skills, the harness tool definitions (the model does not call tools — the harness around it does), the codebase, and the running conversation. A fresh session starts around 20,000 tokens on this account and compaction kicks in near the 250,000 limit.
Do NOT write the skill first — run the workflow by hand with the agent
The mistake is going straight from 'I have a workflow' to 'create a skill'. Instead, walk the agent through the job one step at a time, in conversation, exactly as you would train a new hire. Correct it when it goes wrong. Only once it has completed the job end to end do you move on.
Have the agent write the skill from that successful run
Tell it: 'Review what you just did and create the skill.' It now has the context of a run that actually worked, which is the thing a hand-written or downloaded skill can never have. Don't hand-write skills — there is even a skill for creating skills.
Repair the skill recursively when it fails
The skill will still miss things. When it fails, ask the agent directly: 'Why did you fail? What error did you get?' It answers descriptively — e.g. a 505 with insufficient credits — which tells you whether it is a credit problem or a logic problem. Feed that failure back, let it fix the run, and then say: 'With the new fix, update the skill so this doesn't happen again.'
Repeat until it holds
The author's report generator pulls from roughly eight data sources (Notion, Dub Analytics, YouTube Analytics, Twitter Analytics and others) and now runs for ten minutes without intervention. That took five iterations of the fail-ask-fix-update loop. No single prompt would have produced it.

Gotchas

A 1,000-line CLAUDE.md is roughly 7,000 tokens re-added on EVERY turn. A skill's name and description costs a couple of hundred, with the body loaded only on a match. If content does not need to be present every single turn, it should be a skill, not a memory file.
The claim is that 95% of people do not need an agent.md / CLAUDE.md at all — the models already read your codebase, so telling them 'this project uses React' is wasted tokens. The 5% that justifies one: genuinely proprietary information, or a methodology specific to you that must be referenced on every turn.
Don't install other people's skills. Two reasons given: a downloaded skill is an easy attack vector, and more fundamentally it lacks the context of a successful run inside YOUR workflow — which is the entire thing that makes a skill work.
Give the agent its own email account rather than access to yours, and forward it what it needs. The author does this specifically because of attack vectors, having been compromised before.
Don't start with 15 sub-agents and 30 skills on day one. Build one agent, build its skills from real runs, then add a sub-agent once there is something to delegate.
Expect roughly two weeks of unglamorous setup before an agent stack feels good. The models are strong; the missing piece is your context, and nobody selling a harness has an incentive to tell you that.