Claude Code vs OpenClaw: what each host actually reads
The two hosts disagree about almost everything: how many instruction files they read, whether personality has a home, where skills land. A skill that assumes one will misbehave in the other.
The file slots
What each host looks for, side by side.
| Context | Claude Code | OpenClaw |
|---|---|---|
| Instructions | AGENTS.md | AGENTS.md |
| Personality | No slot | SOUL.md |
| Tool notes | No slot | TOOLS.md |
| Skills | .claude/skills/<name>/SKILL.md | skills/<name>/SKILL.md |
| Workspace root | The repository | ~/.openclaw/workspace |
Two rows carry most of the consequences: OpenClaw reads three separate context files where Claude Code reads one, and two of those files have nowhere of their own to live on Claude Code.
Files merge and split
Because the number of files differs, the plugin reshapes context on the way to its destination:
- Going to Claude Code, files join. Three OpenClaw files become one, each under its own heading.
- Going the other way, one file may split. Claude Code's single file is divided along its subjects.
File identity does not survive
SOUL.md" points at a filename that may not exist at the destination. Point at a heading ("the voice described under Voice and tone") because headings survive merging and filenames do not.Where skills land
Skills are the portable part. Both hosts read a folder per skill containing a SKILL.md, so the same skill works in both without reshaping; only the parent directory differs, and the plugin decides that.
That is why skills are the unit worth investing in: the format is the same everywhere. The SKILL.md anatomy page covers what goes in one.
Writing for both
Four substitutions cover most of what goes wrong:
| Instead of | Write |
|---|---|
| "In Claude Code, use the Bash tool to run the tests." | "Run the project's test suite before reporting back." |
"Follow the voice described in SOUL.md." | "Follow the voice described under Voice and tone." |
"Your skills are in .claude/skills/." | Delete it. The agent already has them. |
"Call linear_search_issues with the ticket title." | "Search existing issues for anything matching the ticket." |
The pattern behind all four: describe the capability and the intent, never the host, the filename, the path, or the tool id.
Choosing a plugin
Which plugin you install depends on where your team already works, not on which is more capable; both sync the same library.
- 1
Claude Code
Installed from the marketplace and driven by slash commands inside a session. Skills land in the repository you are working in. Set it up.
- 2
OpenClaw
Installed from ClawHub and configured on the gateway host, authenticating with an API token. Skills land in the OpenClaw workspace. Set it up.
Installing both is normal. The library is the source of truth in either case, so a skill edited once appears in both.