claw-collections

Reusable OpenClaw workspace bundles ("collections") — agent files, skills, cron jobs, plugins, and exec approvals that seed a Claw's filesystem at startup.

A collection is a directory tree. The claw-operator seeds it into a running Claw's persistent volume on first boot, via spec.agentFiles on the Claw resource. You point a Claw at a collection in one of two ways:

• Git — spec.agentFiles.git (URL + optional ref/path), or
• Upload — the deployer dashboard packages a folder and wires it up for you.

Seeding works with both operator-managed (the default) and user-managed (spec.config.management: user) modes. It runs once on first boot (apply policy IfMissing); edits made later inside the running Claw are preserved across restarts. In operator-managed mode, the operator adds infrastructure skills (PLATFORM.md, KUBERNETES.md) on top of what agentFiles seeds.

Examples

Collection	What it shows
software-qa-mcp	Software Q&A agent backed by an MCP server (Context7), plus a verification sub-agent and a per-workspace skill
enterprise-profiles	Per-department assistant profiles (HR, Finance, Executive) for the enterprise onboarding pattern

New collections go here — one row per top-level directory.

Selecting a collection over Git

This repo holds many collections, one per top-level directory. Point a Claw at one with:

Field (spec.agentFiles.git / deployer)	Value
url / Git URL	https://github.com/redhat-et/claw-collections.git
ref / Git ref	a branch or tag (e.g. main) — not a commit SHA
path / Path in repo	the bundle directory, e.g. my-bundle

The path is the directory that directly contains workspace-main/, openclaw.json, etc. — its contents become the bundle root. Leave path empty only if the bundle is the whole repository root.

ref must be a branch or tag: the operator clones with git clone --branch, which does not accept commit SHAs.

---

How a collection maps onto disk

The Claw mounts its OpenClaw home at ~/.openclaw (on its PVC). Each top-level entry of your collection is placed there like this:

In your collection	Lands at	Notes
openclaw.json	merged into the Claw's effective config	Not copied as a file — it's the config seed
workspace-main/	~/.openclaw/workspace/	The main agent's workspace
workspace-<id>/	~/.openclaw/workspace-<id>/	One per sub-agent (see below)
skills/	~/.openclaw/skills/	Shared skills (requires config — see below)
cron/jobs.json	~/.openclaw/cron/jobs.json	Scheduled jobs
plugins/	~/.openclaw/plugins/	Requires config — see below
exec-approvals.json	~/.openclaw/exec-approvals.json	Pre-approved exec allowlist

A collection is more than files. Skills directories, plugin paths, cron enablement, and sub-agent workspaces all have to be declared in your openclaw.json — OpenClaw will not pick them up by location alone. The rest of this doc is the wiring you need.

---

openclaw.json — the config seed

Your openclaw.json is deep-merged into the Claw's effective config. This is where agents, skills discovery, plugin paths, and cron live.

{
  "agents": {
    // Do NOT set agents.defaults.workspace here — leave it unset so each
    // agent resolves to the workspace path you give it below.
    "list": [
      {
        "id": "default",
        "default": true,
        "name": "Main",
        "workspace": "~/.openclaw/workspace",
        "subagents": { "allowAgents": ["builder", "research"] }
      },
      { "id": "builder",  "name": "Builder",  "workspace": "~/.openclaw/workspace-builder" },
      { "id": "research", "name": "Research", "workspace": "~/.openclaw/workspace-research" }
    ]
  },

  // Needed ONLY for a shared top-level skills/ dir (see Skills below).
  "skills":  { "load": { "extraDirs": ["~/.openclaw/skills"] } },

  // Needed ONLY if you ship a plugins/ dir (see Plugins below).
  "plugins": { "load": { "paths": ["~/.openclaw/plugins"] } },

  // Needed to run cron/jobs.json.
  "cron":    { "enabled": true }
}

Provider/model credentials are managed by the Claw spec (the deployer fills these in) — don't put API keys in openclaw.json.

---

The main agent — workspace-main/

Seeds ~/.openclaw/workspace/, the default agent's working directory. Typical contents (all optional):

workspace-main/
├── AGENTS.md        # operating instructions for the agent
├── SOUL.md          # persona / style / principles
├── IDENTITY.md      # name, vibe
├── USER.md          # who the human is
├── MEMORY.md        # root memory file (auto-indexed)
├── memory/          # additional memory files (*.md, auto-indexed)
└── skills/          # per-agent skills (auto-discovered, see below)
    └── <skill-name>/SKILL.md

Sub-agents — workspace-<id>/

One sibling directory per sub-agent, where <id> matches an entry in agents.list. Each lands at ~/.openclaw/workspace-<id>/.

Important: OpenClaw resolves a sub-agent's workspace from its workspace field. Because collections are seeded as siblings, give every sub-agent an explicit "workspace": "~/.openclaw/workspace-<id>" in openclaw.json (and do not set agents.defaults.workspace, or sub-agents resolve to ~/.openclaw/workspace/<id> instead and won't find their seeded files).

workspace-builder/
├── AGENTS.md
└── SOUL.md

Skills

Skills are discovered per-workspace by default, at <workspace>/skills/<name>/SKILL.md. So the simplest place for a skill is inside the agent that uses it:

workspace-main/skills/docs-answering/SKILL.md      # auto-discovered, no config

For a shared skills library used across agents, put it at the top level and register the directory in openclaw.json:

skills/docs-answering/SKILL.md                      # -> ~/.openclaw/skills/

{ "skills": { "load": { "extraDirs": ["~/.openclaw/skills"] } } }

A top-level skills/ is not discovered without that extraDirs entry.

Cron jobs — cron/jobs.json

Lands at ~/.openclaw/cron/jobs.json (OpenClaw's default cron store). Enable cron in config:

{ "cron": { "enabled": true } }

// cron/jobs.json
{ "version": 1, "jobs": [ /* job entries per OpenClaw's cron schema */ ] }

Plugins — plugins/

There is no default ~/.openclaw/plugins scan. Ship the dir and point the loader at it:

plugins/<plugin>/...                                # -> ~/.openclaw/plugins/

{ "plugins": { "load": { "paths": ["~/.openclaw/plugins"] } } }

Exec approvals — exec-approvals.json

Lands at ~/.openclaw/exec-approvals.json and seeds the command allowlist on boot. Use it to pre-approve commands the agent may run non-interactively. Follow OpenClaw's exec-approvals format.

MCP servers — NOT a bundle file

OpenClaw does not read a loose ~/.openclaw/mcp.json. Declare MCP servers on the Claw resource (spec.mcpServers) instead of in the collection. (If you have an old installer-style mcp.json, migrate it to the Claw spec.)

---

Example collection

my-collection/
├── openclaw.json                 # agents + skills/plugins/cron wiring
├── workspace-main/
│   ├── AGENTS.md
│   ├── SOUL.md
│   └── skills/
│       └── triage/SKILL.md       # per-agent skill (auto-discovered)
├── workspace-builder/            # sub-agent (needs explicit workspace in openclaw.json)
│   └── AGENTS.md
├── skills/
│   └── shared-research/SKILL.md  # shared skill (needs skills.load.extraDirs)
├── cron/
│   └── jobs.json
├── plugins/
│   └── my-plugin/...
└── exec-approvals.json

---

Quick checklist

• Claw CR with spec.agentFiles pointing at your collection
• Main agent files under workspace-main/
• Each sub-agent has a workspace-<id>/ dir and an explicit workspace in openclaw.json; agents.defaults.workspace is left unset
• Per-agent skills under workspace-*/skills/; shared skills under skills/ with skills.load.extraDirs
• cron.enabled: true if you ship cron/jobs.json
• plugins.load.paths: ["~/.openclaw/plugins"] if you ship plugins/
• MCP servers go on the Claw spec.mcpServers, not in the collection
• No API keys in openclaw.json (credentials are managed on the Claw spec)