Why this exists
Knowing something and being able to do it are different problems.
You could teach the agent a new workflow by retraining the model — but that takes weeks, GPUs, and huge datasets. Or you could let the agent run arbitrary shell commands on your laptop — but that's a security nightmare. Neither works for everyday users.
OpenClaw splits the problem: Skills are just text (markdown files) that get dropped into the model's context so it learns how to handle specific situations. Nodes are tiny companion apps on your devices that expose safe, explicit capabilities (take a photo, get location, run this specific command). The agent reads a skill to know what to do, then calls a node to actually do it.
Skills Platform
Skills are markdown files injected into the agent's context. They teach the agent specific workflows without changing the model. Think employee training manuals, not model fine-tuning.
In plain terms
Markdown is just plain text with light formatting (# for headings, * for bullets). Skills are
literally markdown files you can edit with any text editor.
Injected into context means the skill's text is automatically pasted into the model's "whiteboard" before it starts thinking. The model reads it the same way it reads your message. No compile step, no magic — just text the model sees.
Fine-tuning (what this
isn't) means permanently altering the model's weights — expensive, slow, and risky. Skills are reversible by deleting a file.
Three Skill Tiers
Bundled
Ship with OpenClaw. Always available. Includes: browser automation, Canvas, cron jobs.
Managed (ClawHub)
Community registry at clawhub.com. Install on demand. Curated and versioned.
Workspace
Your skills at ~/.openclaw/workspace/skills/<name>/SKILL.md. Active immediately, no restart.
Creating a Workspace Skill
# Create a custom skill
→ mkdir -p ~/.openclaw/workspace/skills/gtm-audit
→ cat > ~/.openclaw/workspace/skills/gtm-audit/SKILL.md << 'EOF'
# GTM Tag Audit
When asked to audit GTM tags:
1. Open the GTM container in the browser
2. List all tags with their trigger conditions
3. Check for duplicate or conflicting tags
4. Verify conversion tracking setup
5. Report findings in a structured table
EOF
# Active immediately — no restart needed
Nodes
Nodes are companion apps (macOS, iOS, Android) that pair with the Gateway via WebSocket and expose device-local capabilities. The agent invokes nodes via node.invoke — it never touches devices directly.
In plain terms
Companion app = a separate app installed on your device (menu bar on Mac, full app on phone) that listens for Gateway requests. Without it, the agent can't touch your camera, your GPS, your shell. With it, every capability is explicit and scoped — the phone's camera doesn't get exposed unless you install and authorize the iOS node.
node.invoke is the single tool the agent uses to call
any device action:
node.invoke("camera.snap", { side: "rear" }). The agent doesn't open cameras directly; it asks the node to do it and trusts the result.
macOS Node
| Action | Description |
|---|
| system.run | Execute shell commands on the host machine |
| system.notify | macOS native notifications |
| canvas.* | Canvas drawing and manipulation |
| camera.snap | Take photos with connected camera |
| screen.record | Screen recording |
| location.get | Device location |
Elevated mode: type /elevated on for host permissions.
iOS Node
Voice Wake, Talk Mode, Canvas, camera, screen recording, Bonjour pairing.
Android Node
Chat + Voice + Canvas, camera, screen recording, notifications, location, SMS, contacts, calendar.
Node Invocation Flow
node.invoke — how the agent uses devices
Pi Agent
│
│ node.invoke("system.run", { cmd: "..." })
│
▼
┌──────────────┐
│ GATEWAY │ ─── routes to registered node
└──────┬───────┘
│
▼
┌──────────────────┐
│ macOS Node │ ─── executes on host
│ (menu bar app) │
└──────┬───────────┘
│
│ { result: "...", exitCode: 0 }
│
▼
Pi Agent ─── processes result, continues loop
Key insight: Skills = what the agent knows. Nodes = what the agent can do. A skill can orchestrate multiple node capabilities — e.g., a "morning briefing" skill that uses camera.snap, location.get, and system.notify together.
Walk-through
A "Morning Briefing" skill in action (7:00 AM)
- step 1 A cron trigger fires at 7:00 AM. Gateway wakes the Pi agent with: "run the morning briefing."
- step 2 Agent reads
skills/morning-briefing/SKILL.md — your custom markdown file that says things like: "Get location. Pull weather. Summarize today's calendar. Snap a photo of the whiteboard in my office. Send everything to the macOS notify + save to Canvas."
- step 3 Agent calls
node.invoke("location.get") on the iOS node. The phone app returns GPS coords.
- step 4 Agent calls a weather tool with those coords. Gets forecast.
- step 5 Agent calls a calendar tool (via a bundled skill) to fetch today's events.
- step 6 Agent calls
node.invoke("camera.snap", { device: "office-mac" }). The macOS node captures a photo, uploads it, returns a URL.
- step 7 Agent composes a briefing, writes it to Canvas, and calls
node.invoke("system.notify", { title: "Morning Briefing", body: "..." }). You see it on your Mac within seconds of waking up.
- step 8 None of this required new code. You edited one markdown file. The agent orchestrated four devices and three tools because the skill told it how.
Common mistakes
- Writing a skill that says "always do X." Absolute rules confuse the model when X doesn't apply. Prefer "when the user asks for Y, do X" — conditional guidance.
- Forgetting that workspace skills are active immediately. There's no install step. Drop a SKILL.md in
~/.openclaw/workspace/skills/<name>/ and the next agent turn sees it. (Also easy to forget: deleting the file removes the skill just as instantly.)
- Putting secrets in SKILL.md. Skill text is injected into the model context every turn — it's not secret. Store API keys in openclaw.json, not in skill markdown.
- Expecting macOS node capabilities to work without
/elevated on. system.run and similar require explicit elevation per session. Without it, the node refuses — by design.
- Installing every ClawHub skill you see. Each one takes context budget every turn. Keep only what you use; prune quarterly.