At a glance
The counts describe the catalog, not your fleet, and they grow as packs are added. The Teams and Agents tab counts in the Marketplace show what your server has loaded.
What the catalog contains
- Pack. A bundle of agents, teams and skills from one source, usually one open-source repository, with one license and one provenance record (repository, pinned commit, authors).
- Agent. One specialist: a card (name, role, emoji, color, description, category, tags and skills) and its texts.
IDENTITY.mdholds its full instructions,SOUL.mda shorter persona, andTOOLS.mdtool notes. The 15 built-in agents also carry anAGENTS.md. - Team. A roster of at least two agents, plus routing: for each member, the
AGENTS.mdtext that says whom it hands work to. A team can also carry a workflow description. - Skill. A named capability an agent’s card lists. The 44 built-in skills appear on the Skills tab. A pack may declare its own skills for its agents, but may not redeclare a built-in one.
AGENTS.md from the team’s routing. Only OpenClaw agents follow IDENTITY.md; on every other runtime the agent runs on SOUL.md plus its personality settings, and IDENTITY.md is kept for reference. The per-runtime table is in What each runtime runs.
Where the catalog comes from
The catalog is not part of the npm package. Only the built-in pack ships inside Clawboo; your Clawboo server downloads the rest:- The first time the dashboard asks for the catalog, the server downloads the catalog index for its own version from the Clawboo repository on GitHub, waiting up to 5 seconds. A release reads the index as it was at its release tag (
clawboo@<version>); a development build reads themainbranch’s. - For each pack the index lists, it reads a copy saved in
~/.clawboo/catalog/, or downloads one. It checks the pack’s SHA-256 digest before reading it and skips a pack that does not match. Saved packs are keyed by their digest, so an unchanged pack is downloaded once. - It merges every pack that passed with the built-in pack, which is always included, so the catalog is never empty.
- It keeps the result in memory for 6 hours. After that, the next request asks GitHub whether the index changed and rebuilds the catalog.
main’s instead. The request carries no account or usage data; it only asks for the published files.
The 6-hour hold also applies to a download that failed. If GitHub could not be reached when the catalog was first needed, the Marketplace shows only the built-in pack (5 teams, 15 agents) until the next refresh. Restart the server (
clawboo restart) to try again sooner.- The index URL is
https://raw.githubusercontent.com/clawboo/clawboo/refs/tags/clawboo%40<version>/catalog/dist/v1/index.jsonfor a release, and the same path onrefs/heads/mainfor a development build. SetCLAWBOO_CATALOG_INDEX_URL, orcatalogIndexUrlin the operator settings file, to serve the same files from a mirror. - When the server runs from a repository checkout that has
catalog/dist/v1/, it reads the catalog from those files instead of GitHub. - An index in a newer format than your Clawboo can read shows only the built-in pack. A single pack it cannot read is left out, and the rest still show.
Packs
The pack names are the pack filters in the Marketplace. Every agent and team id is the pack’s prefix plus a slug, for example
agency-engineering-frontend-developer, and is unique across the catalog. Every pack is at content version 1.0.0.
Sources
Clawboo Life and Home and the built-in pack are written for Clawboo. The other 17 are adapted from these repositories, each pinned to the commit it was taken from:
Every pack ships a
NOTICE.md, and attribution is collected in THIRD_PARTY_NOTICES.md (see License and notices). The 140 entries from Agency Agents (116) and Research and Orchestration (24) also link to the exact upstream file they came from (origin.url); the other packs record provenance once, at pack level. A pin records where content came from; nothing fetches the upstream repositories again. The 17 packs are marked adaptation: "adapted", and their bodies have the upstream YAML frontmatter removed.
Pack format
A pack is a folder of JSON files. The public specification is JSON Schema 2020-12 in the repository:catalog/schema/pack.schema.json describes a pack, and catalog/schema/index.schema.json the browse index. You can write a pack against those two files without installing anything. Inside the repository, packages/pack-format holds the same format in TypeScript.
The manifest
provenanceis recorded once per pack:sourceId,label,color(#RRGGBB),repo,ref(the pinned commit),license(an SPDX id),authors,adaptation(verbatim,adaptedororiginal) andimportedAt(an ISO time). An entry from a different upstream can override it with anoriginblock (url,adaptation,authors).renamesis entry bookkeeping, not a schema migration. The built-in pack maps its five old team ids, such asdev, to the current ones, such asclawboo-dev.categoryvalues are open: 19 are known (for exampleengineering,marketing,research,support), and a pack that uses another must list it innewCategories.
Listings and bodies
A listing is what a card shows; a body is what the detail view and a deploy need. They are separate files because the agent texts are most of the bytes and no card reads them.filesis a map, so a pack can carry another agent file without a format change.- At deploy, Clawboo writes
SOUL.mdwith the default personality added,IDENTITY.mdwith the agent’s final name (a number is added when the name is taken), anAGENTS.mdbuilt from the team’s routing and Clawboo’s team instructions, and aCLAWBOO.mdhelp file. On an OpenClaw member, theTOOLS.mdtext goes intoAGENTS.mdunder## Tools; other runtimes do not get it. suggestedRuntimeanddefaultRuntimeare optional hints the team dialog uses to preselect a runtime. No pack sets them.
Versions
schemaVersion is required, must be an integer, and is never assumed. Version 1 is the only one, so this Clawboo reads exactly version 1. A pack that fails is rejected on its own, and the rest of the catalog still loads.
Catalog routes
The dashboard reads the catalog from its own server:sourceUrl is the entry’s origin.url, when it has one. Full shapes and examples are in the Catalog API.
For contributors
Repository layout
Repository layout
catalog/ is not a pnpm workspace member and is in no turbo task: a pack is content, not code. catalog/dist/ is committed, which is what lets the default index URL (a raw GitHub URL on main) serve the catalog with no deploy step.Add or change a pack
Add or change a pack
Edit the files under
catalog/packs/<publisher>/<slug>/, then run:catalog:build regenerates catalog/dist/ and the compiled built-in pack. catalog:verify runs every content rule, then checks that catalog/dist/ and the compiled built-in pack are byte-for-byte what a rebuild would write. Commit the regenerated files with your change.What catalog:verify checks
What catalog:verify checks
- The pack validates against the schema (strictly, with stale versions treated as errors), and every listing’s body file exists and validates. A body file no listing points to is an error.
- A pack with
provenance.repoships a non-emptyNOTICE.md. - Every
skillIdsentry resolves to a built-in skill or one of the pack’s own, and a pack does not redeclare a built-in skill. - A category the dashboard has no label for is listed in
newCategories, andnewCategorieslists only new, used categories. - No two packs emit the same id prefix, and no two packs claim the same id.
- Descriptions are at least 20 characters and do not end in
.... AnIDENTITY.mddoes not open with YAML frontmatter (---) and is at most 50,000 characters. No entry repeats a tag. - A team has at least two members, routes only to its members, and has routing for every member.
- No string names a competing registry, installer or chat invite.
- No text trips the prompt-injection scan, except findings reviewed in
scripts/catalog/injection-allowlist.ts.
node scripts/catalog/budget.mjs separately keeps the compiled built-in pack under 128 KB and the index under 512 KB.Digests and canonical bytes
Digests and canonical bytes
Each pack row in
index.json names one bundle by version and carries integrity, a sha256-<base64> digest of the bundle’s exact bytes. The server recomputes the digest and compares it before parsing the bundle, so bytes that do not match are never parsed.Bundles and the index are written as canonical bytes: object keys sorted recursively, no insignificant whitespace, LF line endings and no trailing newline. Those exact bytes are written, served and hashed, which is why Prettier never touches catalog/dist/ (its **/dist/ ignore entry). Pack sources under catalog/packs/ are ordinary Prettier-formatted JSON.The built-in pack
The built-in pack
The built-in pack (
catalog/packs/clawboo/builtin) is compiled into Clawboo, because first-run onboarding offers no start-from-scratch path and needs teams to pick from. pnpm catalog:build generates it into two files, one per build target, and catalog:verify fails if either drifts from the pack:Never edit them by hand.
CI for content pull requests
CI for content pull requests
A pull request that changes only
catalog/ skips the full CI matrix and runs .github/workflows/catalog-ci.yml: the content rules, the injection scan and the size budgets, offline. A change under catalog/packs/clawboo/ gets the full matrix, because that folder holds the built-in pack, which ships inside Clawboo.Never make catalog-ci.yml a required check. It is path-filtered, so it never reports on other pull requests, and GitHub would keep them waiting. The catalog-verify job in ci.yml runs the same checks on every code pull request; require that one. Publishing a release runs pnpm catalog:verify too.Related
- Browse and deploy from the Marketplace: search, details, deploy, and what each runtime runs.
- Catalog API: the three catalog routes in full.
- License and notices: licenses and attribution for the adapted packs.
- Agents: the agent files a deployed agent gets, per runtime.
- Configuration:
~/.clawboo/catalog/and the other files Clawboo keeps.