openclaw/agent-skills: shared SKILL.md workflows for Codex and Claude Code

The problem: the same SKILL.md copied into every repo

A coding agent only follows a workflow it can read. If your team wants every review to close out the same way, or every remote validation run to hit the same CI-parity target, that workflow has to exist as a file the agent can load. The obvious shortcut is to paste the same SKILL.md into each repository. The README describes the outcome plainly: the project exists so you can "write a workflow once, reuse it everywhere, and avoid hand-copying long `SKILL.md` files across every repo."

The intended audience is narrow. This is for people working on OpenClaw projects, and the README is explicit that repo-specific product skills should stay in the repo they describe. An `acpx` usage skill belongs in `openclaw/acpx`. Only general helpers, review closeout, remote validation, handoff, belong in the shared catalog. That boundary is the whole design, and it is the first thing to check against your own situation.

What ships in the catalog and how the directories are laid out

The repository lists eight skills: `agent-transcript`, `autoreview`, `behavior-validator`, `beam`, `crabbox`, `handoff`, `readme-standard`, and `session-viewer`. Each lives in `skills/<name>/` and must contain a `SKILL.md`. Helper scripts belong inside that skill's own `scripts/` directory, which keeps a skill self-contained when it is copied elsewhere.

The layout is worth reading before you install anything, because it tells you what a skill can carry. `autoreview` has a `SKILL.md` and a `scripts/` directory. `behavior-validator` has `SKILL.md` and `references/`. `beam` has all four: a README, a SKILL.md, references, and scripts. `crabbox` and `handoff` are single files. Two scripts sit outside the skills tree: `scripts/install-skills` and `scripts/validate-skills`.

`autoreview` is singled out as a candidate for a zero-setup snapshot in flagship repos, since review closeout is part of the contribution workflow. The README treats that snapshot as a distribution artifact rather than a source of truth: edit canonical skills here first, sync downstream after review, and add provenance and drift checks when a repo vendors a snapshot. If you vendor by hand, you have created two sources of truth and no check that catches the divergence.

Installing agent skills with scripts/install-skills

The install path is a shell script in the repository, not a package manager. Clone first, then inspect what is available before anything touches your home directory.

git clone https://github.com/openclaw/agent-skills.git
cd agent-skills
scripts/install-skills --list

The `--list` flag prints the available skills. A dry run shows what an install would change without writing to disk:

scripts/install-skills --dry-run

Running the script with no arguments installs all skills into the default agent skill directory. To install only what you need, pass skill names:

scripts/install-skills autoreview crabbox

By default the script symlinks. The README recommends symlinks for local development, because changes in the checkout are immediately visible to the agent. For a portable or locked-down setup, switch to copies and point at a different target:

scripts/install-skills --mode copy --target ~/.agents/skills

If a skill is already installed and you want the checkout to win, use `--force`:

scripts/install-skills --force autoreview

For Codex, the README gives a manual symlink instead, creating `~/.codex/skills` and linking the repository's `skills` directory into it as `agent-skills`. For Claude Code the same pattern applies with `~/.claude/skills`. If that directory already points at another shared skills folder, the README says to add symlinks inside that folder instead, one per skill. The reasoning is the same in both cases: one checkout, several agents reading from it.

Validating skills before you trust them

A skill file with broken YAML frontmatter is a file the agent cannot route. The repository ships a frontmatter-only check for exactly that case:

scripts/validate-skills

It checks every `skills/*/SKILL.md` for YAML frontmatter plus required `name` and `description` strings. Frontmatter must be a mapping enclosed by standalone `---` lines. Trailing spaces or tabs are allowed on the closing line, which is a small allowance that saves a class of false failures.

The full check is heavier. Development checks use Python 3.14 and Node.js 26, matching CI, and the README walks through a virtual environment, `requirements-dev.txt`, and `npm ci --ignore-scripts` before running `python scripts/check-skills`. That command runs frontmatter validation, syntax checks, all Python and Node tests, and `npm run typecheck` for the session viewer. The Node packages are development-only, so an installed skill does not need `npm install`. A separate macOS CI job installs a pinned Codex CLI to exercise native sandbox access controls without a reviewer account or provider request. If you only consume skills, you never need that toolchain. If you edit them, you do.

Where this catalog is the wrong tool

The admission boundary is the main limitation, and it cuts in both directions. If your workflow describes one product, the README says it belongs in that product's repository, not here. Contributing it anyway creates a skill that is installed everywhere and useful almost nowhere.

The second limitation is that the catalog is a workflow library, not a runtime. Nothing here executes on your behalf: the skills are Markdown instructions plus helper scripts, and the helper scripts are only as good as the commands they wrap. `crabbox` is described as a remote validation workflow for broad or CI-parity proof, which means it depends on that remote infrastructure being reachable and configured. There is no fallback described for a machine that cannot reach it.

The third is data handling, and the README raises it directly. Session exports can contain sensitive conversation data, and `session-viewer` HTML should be treated as local or private output unless it has been separately redacted and reviewed. `agent-transcript` is described as local-only and redacted, and `beam` as authenticated and redacted publication to a read-only catalog. Those adjectives are claims about the skills' design, not guarantees about your inputs. The editing rules add a constraint that is easy to violate in a hurry: do not include secrets, private hostnames, private account IDs, or private URLs.

How this differs from a skills marketplace

The closest thing to compare against is a general agent skills marketplace or a personal cross-tool skills collection, where anyone publishes a skill and users install whatever they find. The difference here is curation. This repository is not a distribution channel for arbitrary skills. It is the canonical source for a small set of workflows used on OpenClaw projects, with a VISION.md that defines catalog boundaries and admission principles.

That changes the maintenance model. A marketplace skill is owned by whoever published it. A skill in this repository is owned by the project and edited in one place, then synced downstream where a snapshot is vendored. It also changes the failure mode: a marketplace gives you breadth and inconsistent quality, while this gives you a short list and a routing rule for anything that does not belong. If you want a large library of third-party skills, this is not that. If you want one review workflow that every repository agrees on, the narrow scope is the point.

Maintenance, licensing and what upgrading actually costs

The repository is MIT licensed with no separate terms described in the README, so reuse and modification are permitted under that licence; the usual caveat applies that licence text governs, not this summary.

Upgrade cost is low for consumers and higher for editors. Because symlinks are the recommended mode for local development, a `git pull` in the checkout is effectively the upgrade, and every agent reading through the symlink sees the new version immediately. That is also the risk: an unreviewed pull changes the workflow an agent follows, with no staging step. Copies avoid that, at the price of going stale silently.

The real maintenance load sits with anyone who vendors a snapshot. The README is unambiguous that the snapshot is a distribution artifact, that canonical edits happen here first, and that repos which vendor a snapshot should add provenance and drift checks. Without those checks, a vendored copy and the canonical skill diverge and nobody notices until an agent follows the wrong instructions. There are no releases retrieved for this repository, so the commit history in the checkout is the version you track.

Editorial conclusion

Adopt it if you work across several OpenClaw repositories and keep copying the same SKILL.md files by hand; skip it if you only need a skill that describes one product, because the README says that belongs in the repo it describes. Before installing, check VISION.md for the catalog boundaries, confirm the scripts/install-skills flags you need on your machine, and decide whether you want symlinks or copies, since the two modes fail differently when the checkout moves.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. openclaw/agent-skills on GitHub
4. README