## How OpenClaw Works
OpenClaw is an **always-on agent runtime** that acts as a control plane for AI automations . Think of it as a small operating system for agents - it continuously listens for events, manages sessions, queues work, and executes tools .
### The Agent Loop (Core Mechanism)
OpenClaw operates through a **serialized agentic loop** per session . Here's how it works:
```mermaid
flowchart TD
A[Input from Channels/CLI/API] --> B[Gateway Control Plane]
B --> C[Session Management & Queue]
C --> D[Agent Runtime]
subgraph D [Agent Loop Execution]
D1[Load Skills Snapshot] --> D2[Build System Prompt]
D2 --> D3[Model Inference]
D3 --> D4{Tool Called?}
D4 -->|Yes| D5[Execute Tool]
D5 --> D3
D4 -->|No| D6[Stream Response]
end
D --> E[Persistence & Memory]
style D fill:#f9f,stroke:#333,stroke-width:2px
```
**Key phases of the agent loop** :
1. **Intake** - Receives requests from messaging channels (WhatsApp, Telegram, Slack), CLI, or APIs
2. **Context Assembly** - Loads skills snapshots, bootstrap files, and session state
3. **Model Inference** - Calls the LLM with assembled prompt
4. **Tool Execution** - If the model calls a tool, it executes and feeds results back
5. **Streaming** - Outputs are streamed as assistant deltas and tool events
6. **Persistence** - Session state is saved for continuity
### Architecture Layers
| Layer | Purpose |
| :--- | :--- |
| **Control Interfaces** | Desktop app, CLI, web UI for human interaction |
| **Messaging Channels** | WhatsApp, Telegram, Slack, iMessage - event sources |
| **Gateway Control Plane** | Routes requests, enforces access, manages sessions |
| **Agent Runtime** | Core AI reasoning, prompt construction, tool orchestration |
| **Tools Layer** | Bash, browser, filesystem, cron - actual execution |
### Queueing & Concurrency
Runs are **serialized per session** to prevent tool/session races and maintain consistency . Sessions can have different queue modes: `collect`, `steer`, or `followup` .
---
## What are Skills in OpenClaw?
Skills are **portable knowledge packages** that teach OpenClaw how to perform specific tasks . Each skill is a directory containing a `SKILL.md` file with YAML frontmatter and Markdown instructions.
### Skill Directory Structure
```
skill-name/ # lowercase, hyphens only
├── SKILL.md # REQUIRED - frontmatter + instructions
├── scripts/ # OPTIONAL - executable code (Python, Bash, etc.)
├── references/ # OPTIONAL - detailed documentation loaded on demand
└── assets/ # OPTIONAL - templates, images, static files
```
### SKILL.md Format
```markdown
---
name: my-skill
description: What this does. Use when user asks about X.
license: MIT
metadata: { "openclaw": { "requires": { "bins": ["python3"] } } }
---
# Skill Instructions
Write clear, imperative instructions here. Use {baseDir} to reference skill folder.
## Step 1
Do this: `command --arg`
## Troubleshooting
Common error → fix
```
### Frontmatter Fields
| Field | Required | Description |
| :--- | :--- | :--- |
| `name` | **Yes** | 1-64 chars, lowercase alphanumeric-hyphens |
| `description` | **Yes** | 1-1024 chars, include "Use when..." |
| `license` | No | SPDX identifier (MIT, Apache-2.0) |
| `metadata.openclaw` | No | Gating rules, installers, requirements |
### Progressive Disclosure (Token Efficiency)
Skills use a **three-stage loading model** to save context tokens :
| Stage | What Loads | When |
| :--- | :--- | :--- |
| **Discovery** | Only `name` + `description` | Session start (~100 tokens) |
| **Activation** | Full `SKILL.md` body | When skill is triggered |
| **Resources** | `references/` files | Only when explicitly referenced |
### Skill Locations & Priority
OpenClaw loads skills from multiple locations with this priority order:
1. **Workspace skills** - `<workspace>/skills` (highest priority)
2. **Project agent skills** - `<workspace>/.agents/skills`
3. **Personal agent skills** - `~/.agents/skills`
4. **Managed skills** - `~/.openclaw/skills`
5. **Bundled skills** - shipped with OpenClaw (lowest priority)
### Skill Gating (Load-Time Filtering)
Skills can be **conditionally loaded** based on environment :
```markdown
metadata: {
"openclaw": {
"requires": {
"bins": ["docker", "python3"],
"env": ["OPENAI_API_KEY"],
"config": ["browser.enabled"]
},
"os": ["darwin", "linux"],
"emoji": "🐳"
}
}
```
**Gating options**:
- `requires.bins` - binaries must be in PATH
- `requires.env` - environment variables must exist
- `requires.config` - config paths must be truthy
- `os` - restrict to specific platforms
### ClawHub (Skill Registry)
OpenClaw has a public skill registry at [clawhub.com](https://clawhub.com) . You can:
```bash
openclaw skills install <skill-slug> # Install to workspace
openclaw skills update --all # Update all skills
```
---
## Can You Make a Generic Agent That Accepts a skills.md File?
**Yes, absolutely.** The Agent Skills format is an **open standard** from [agentskills.io](https://agentskills.io) . This means skills are **portable across multiple platforms**, including:
- Claude Code
- Cursor
- GitHub Copilot
- OpenClaw
- VS Code (via symlinks)
- Any custom agent that implements the spec
### Building Your Own Generic Agent
You can build an agent that:
1. **Scans directories** for folders containing `SKILL.md`
2. **Parses YAML frontmatter** to get `name` and `description`
3. **Injects the manifest** into the system prompt
4. **Loads full SKILL.md** when the LLM indicates the skill is relevant
5. **Provides tool execution** for actions described in the skill
### Example: Minimal Agent Logic
```python
# Pseudocode for skill loading
skills = []
for skill_dir in scan_directories():
if (skill_dir / "SKILL.md").exists():
metadata = parse_frontmatter(skill_dir / "SKILL.md")
skills.append({
"name": metadata["name"],
"description": metadata["description"],
"path": skill_dir
})
# Inject manifest into system prompt
system_prompt = f"Available skills: {skills}\n\nWhen a skill is relevant, ask to load it."
# On skill trigger
if triggered_skill:
full_content = (triggered_skill["path"] / "SKILL.md").read_text()
# Inject into context and continue
```
### Validation Tools
You can validate skills using the official CLI :
```bash
uv tool install git+https://github.com/agentskills/agentskills#subdirectory=skills-ref
skills-ref validate ./my-skill
skills-ref read-properties ./my-skill
skills-ref to-prompt ./my-skill
```
---
## What Other Files Exist Alongside SKILL.md?
Yes, skills can include **three optional subdirectories** :
### 1. `scripts/` - Executable Code
Contains runnable scripts that the agent can execute:
```
scripts/
├── validate.py
├── process_data.sh
└── generate_report.js
```
Use in SKILL.md: `Run: python scripts/validate.py --input {file}`
### 2. `references/` - Detailed Documentation
Loaded **on-demand** to save context tokens:
```
references/
├── api_documentation.md
├── policies.md
├── architecture.md
└── troubleshooting.md
```
Reference in SKILL.md: `See [references/policies.md](references/policies.md) for details`
### 3. `assets/` - Static Resources
Templates, images, fonts, or any static files:
```
assets/
├── report-template.docx
├── diagram.png
├── config-schema.json
└── logo.svg
```
### Complete Example: OpenClaw-Skill Structure
A real-world example (OpenClaw-Skill) has **51 reference files** covering everything from architecture to troubleshooting :
```
OpenClaw-Skill/
├── SKILL.md # Main entry point
└── references/
├── architecture.md # Gateway architecture
├── agent_runtime.md # Agent loop details
├── channels.md # 20+ channel configs
├── providers.md # 35+ model providers
├── security.md # Security baseline
└── ... (46 more files)
```
---
## Summary Table
| Question | Answer |
| :--- | :--- |
| **How does OpenClaw work?** | Always-on agent runtime with serialized agent loop per session; Gateway routes requests → Agent loads skills → Model reasons → Tools execute |
| **What are Skills?** | Portable directories with `SKILL.md` containing YAML metadata + Markdown instructions |
| **Required files?** | Only `SKILL.md` with `name` and `description` frontmatter |
| **Optional files?** | `scripts/`, `references/`, `assets/` subdirectories |
| **Generic agent possible?** | **Yes** - Agent Skills is an open standard; works across Claude Code, Cursor, OpenClaw, and custom agents |
| **Skill validation?** | Official `skills-ref validate` CLI tool |
| **Skill registry?** | ClawHub at clawhub.com |
Would you like me to help you create a specific skill for your use case, or dive deeper into building a custom agent that uses the Agent Skills format?
