Skills Should Travel With the Work
I use Claude Code and OpenClaw a lot.
Claude Code is where I spend focused engineering time: inside a repository, changing code, reading tests, opening PRs, fixing the thing in front of me.
OpenClaw is different. It is closer to a personal operating system for agents. It talks to Telegram, my browser, files, cron jobs, local tools, accounting systems, and all the messy glue around real life.
Both are useful. Both have skills. And right now the annoying part is that skills do not travel well enough between them.
That feels like the wrong abstraction boundary.
Skills are not tool configuration
A good skill is not just a command wrapper.
It is procedural memory.
It says:
- how this project deploys
- what traps to avoid
- where the source of truth lives
- what order to do things in
- what must be verified before saying “done”
- what style the output should have
That knowledge should not belong to Claude Code or OpenClaw. It should belong to the work.
If the skill is about a project, it should live with the project.
If the skill is about my blog, my accounting, or my home automation, it should live in my personal agent workspace.
If the skill is generally useful, it should be published somewhere others can install it.
But the core workflow should not have to be rewritten every time I use a different agent runtime.
The shape I want
The simplest version is just this:
skill-name/
SKILL.md
scripts/
references/
assets/
SKILL.md contains the instructions. Scripts contain deterministic helpers. References contain long docs that should only be loaded when needed. Assets contain templates or files the agent may use.
This is already close to how Claude Code skills work, and it is close enough to how OpenClaw skills work that the overlap is more interesting than the differences.
So I do not want a grand new standard.
I want a portable subset.
Three kinds of skills
I think skills naturally fall into three buckets.
1. Public skills
These are generic and safe to share.
Examples:
- review a GitHub PR
- publish a Hugo blog post
- inspect a Rails Hotwire app
- process receipts
- extract frames from a video
They must not contain secrets, private paths, internal URLs, or “works only on my laptop” assumptions.
These belong in a marketplace or public repository.
2. Project skills
These should be committed to the repository.
Examples:
- how to deploy this service
- how to run the test suite correctly
- how to cut a release
- how to debug production incidents
- how to update generated API clients
This is the most underrated category.
Every mature project has tribal knowledge. Usually it lives in Slack, in one senior engineer’s head, or in a README nobody trusts. A project-local skill is a better home for that knowledge because it is written directly for an agent that will actually perform the workflow.
The skill travels with the code.
3. Personal skills
These are mine.
They know about my Obsidian vault, my accounting setup, my home automation, my blog repository, my local tools, my preferences.
They are not meant to be public. Some may contain private assumptions. Some may call OpenClaw-specific tools like messaging, reminders, or node control.
That is fine. Not everything needs to be portable.
The important thing is to know which category a skill belongs to.
The rule: core workflow first, adapter second
The mistake would be to write every skill as “call tool X with parameters Y”.
That makes the skill brittle and runtime-specific.
Better:
- describe the workflow in agent-neutral terms
- keep deterministic operations in scripts
- put runtime-specific behavior behind small adapter notes
For example:
When publishing the post:
1. Create the Hugo markdown file.
2. Use a timestamp safely in the past, because Hugo skips future posts.
3. Run the local build.
4. Commit the result.
5. Push only after explicit confirmation.
In Claude Code: use shell commands inside the repository.
In OpenClaw: use the gateway/browser/message tools only when needed.
The skill should teach the agent what “done” means. The runtime can decide how to execute.
What I want from interop
I want one source of truth and thin installation targets.
Something like:
~/agent-skills/
public/
project/
personal/
Then a small sync tool can install them where each agent expects them:
skillsync install ~/agent-skills/public ~/.claude/skills
skillsync install ~/agent-skills/personal ~/.openclaw/workspace/skills
skillsync validate ~/agent-skills
skillsync package ~/agent-skills/public/hugo-publisher
The sync tool should be boring:
- validate front matter
- reject secrets before packaging
- check broken relative links
- warn about runtime-specific tools
- copy or symlink skills into the right place
- package marketplace-compatible archives
No magic. Just hygiene.
Why this matters
Agents are getting better very quickly, but the bottleneck is often not model intelligence.
The bottleneck is context.
Not “more tokens” context. Operational context.
The little things:
- this command must be run from that directory
- this deployment takes ten minutes and lies about being finished
- this project uses
make test, but only after generating fixtures - this blog needs a past UTC timestamp or Hugo silently skips the post
- this API returns 200 even when the operation failed
That is the stuff that makes agents useful in real work.
And that knowledge should be durable, versioned, reviewable, and portable.
A skill is a pretty good unit for that.
My current opinion
Skills should live as close as possible to the thing they describe.
Project workflow? Put it in the repo.
Personal workflow? Put it in the personal workspace.
Reusable workflow? Publish it.
Agent-specific instructions are allowed, but they should be adapters, not the core.
If we get this right, Claude Code, OpenClaw, and whatever comes next can share the same procedural memory instead of each building its own little island.
That is the interop I actually want.