AIClaw has a lot of moving parts: tools, MCP servers, memory, planning, channels, and reusable Skills. One practical problem shows up quickly when you install many Skills: if every Skill is injected into every prompt in full, context usage grows for no real benefit.
This article is about an existing AIClaw feature, not a new release. The current codebase already uses a two-stage Skill design that keeps prompts smaller while still letting an agent pull in full instructions when they are actually needed.
The problem
In many agent systems, reusable instructions become expensive over time.
- You want a library of focused Skills.
- You do not want every conversation to pay the token cost for all of them.
- You still need the agent to discover what is available and decide when to load more detail.
AIClaw solves that by separating Skill discovery from full Skill loading.
Stage 1: inject the Skill index
The README describes the core idea directly: AIClaw first injects Skill names, descriptions, and paths. That gives the model a compact catalog of what exists without forcing the full SKILL.md content into every request.
In practice, this means an agent can see:
- the Skill name
- a short description
- where the Skill lives
That is enough for planning. If the agent decides a Skill is relevant, it can then read the full instructions.
Stage 2: read full instructions only when needed
The second stage is demand loading. Instead of paying prompt cost up front, AIClaw lets the model fetch the detailed Skill content only when the current task justifies it.
This matters for real usage:
- large Skill libraries stay manageable
- generic chats stay lightweight
- specialized tasks can still pull in deep instructions
The result is a better tradeoff between capability discovery and prompt size.
Built-in, local, and pending Skills
AIClaw does not treat all Skills the same. The current app exposes three practical states.
1. Built-in Skills
Built-in Skills ship with the application. On startup, AIClaw syncs embedded builtin SKILL.md files to the workspace Skills directory, so the runtime has a consistent on-disk view.
2. Local Skills
Local Skills live under the workspace skills/ directory. The admin UI lists them separately, including metadata such as directory name, version, author, and whether the Skill has an executable entry file.
That makes Skills more than prompt snippets. They can also behave like reusable tool bundles.
3. Pending Skill candidates
This is the part I like most in the current implementation.
The Skills page explains that successful multi-tool Agent runs using three or more distinct tools can archive a candidate into skills-pending/. From there, a user can:
- preview the candidate
- promote it into an active Skill
- discard it
This turns useful ad hoc agent behavior into a reviewable workflow instead of silently mutating the prompt library.
Why the promotion step matters
Auto-generated Skills are powerful, but automatic activation would be noisy and risky. AIClaw keeps a human checkpoint in the middle.
The promotion flow in the current handlers and UI requires:
- a final Skill name
- a description
- explicit promotion into the active Skills directory
That gives teams a simple governance model:
- agents can suggest reusable workflows
- humans decide which ones become permanent assets
User workflow in practice
Here is the practical loop the current product supports:
- Install or create Skills in the workspace.
- Let agents see a compact Skill catalog during prompt construction.
- Allow the agent to read a full Skill only when the task needs it.
- Review pending Skill candidates created from successful multi-tool runs.
- Promote the useful ones into the active Skill library.
This design is small, but it changes how an agent system scales. Instead of treating every reusable instruction as permanent prompt baggage, AIClaw treats Skills like indexed assets with on-demand expansion.
A concrete example
Imagine a team has Skills for:
- deep research
- web scraping
- data cleanup
- browser automation
- report generation
With one-stage loading, every conversation drags all of that context around. With AIClaw's current two-stage approach, the agent only needs the index first. A simple file-editing task does not need the full research workflow. A browser-heavy task can load the browser Skill when it becomes relevant.
That is a cleaner model for both cost and reasoning.
Why this is a useful pattern beyond AIClaw
The broader idea is simple: agent capability catalogs should be cheap to expose and expensive details should be loaded lazily.
AIClaw applies that idea in a way that is easy to understand from the repo today:
- compact discovery
- explicit demand loading
- reviewable Skill promotion
- support for both instruction-only and executable Skills
For self-hosted agent platforms, that is a pragmatic design choice. It keeps the system extensible without making every prompt bloated by default.
If you are exploring AIClaw, the Skills page and the skills/ plus skills-pending/ workflow are worth a close look. They show how the project treats reusable agent behavior as something structured, inspectable, and incrementally promotable instead of just more text in the system prompt.