The ClawHub skill format

The ClawHub skill format is almost aggressively simple, and the simplicity is load-bearing: a skill is a folder, and the only file it must contain is SKILL.md. Everything the registry knows about that skill afterwards comes from one YAML block at the top of it.

What the folder holds

• SKILL.md is required, with skill.md accepted as an alternative spelling and the older skills.md still honoured.
• Any ordinary supporting files can sit beside it, and publish accepts them regardless of extension, subject to ignore files, hidden paths, symlinks and the server-side size caps.
• A .clawhubignore controls what publishing skips, and a .gitignore is honoured too, which means a folder that was already tidy for git is usually already tidy for the registry.
• The CLI writes its own install metadata into a .clawhub directory beside the skill and a lock file in the working directory, so those are outputs rather than things you author.

Security scanners receive the complete stored artifact; text detection is a rendering and analysis concern, not an upload allowlist.

The frontmatter is the listing

Metadata is declared in the YAML frontmatter at the top of SKILL.md, and the server extracts it during publish. The description becomes the skill's summary everywhere it appears, in the interface and in search, so it is the one line most readers will judge the skill on. Runtime requirements go under a metadata.openclaw block, which is what tells both the registry and the security analysis what the skill actually needs in order to run.

Naming, and the two limits

• For a portable Agent Skill the name should match the parent directory and use one to sixty-four lowercase letters, numbers or hyphens.
• ClawHub keeps the routable slug and the catalogue display name separate, so a name that came from another client stays publishable and is never silently rewritten, though a long one may be shortened visually without changing what is stored.
• Two server-side limits matter: the total bundle is capped at 50 MB, and the embedding text covers SKILL.md plus roughly forty bounded UTF-8 files on a best-effort basis.

That second limit is the one people are surprised by, because it does not mean the rest of the bundle is ignored. Scanners receive the complete stored artifact either way; what the cap bounds is the text analysis and preview layer. Files that are bounded and valid UTF-8 can be previewed as escaped plain text, and everything else keeps its exact bytes and stays downloadable. For the publish path these files travel, see What ClawHub checks before publishing and ClawHub quickstart.

The importer is stricter than the CLI

Publishing from the web GitHub importer is not the same as publishing locally, and the difference catches people out. The importer only discovers skill files in public, non-fork repositories owned by the signed-in GitHub account. Private repositories, forks, archived or disabled repositories and third-party public repositories are all out of scope for it, while local publish and sync have no such restriction. If an import silently finds nothing, that list is the first thing to check. See The ClawHub CLI for the local path and How ClawHub works for what the registry does with the result.

On Diali

Diali hosts OpenClaw, so a skill you publish is installed into an assistant that is already running. Each customer runs their own, the runtime configuration is generated from the dashboard and replaced at each release, and state lives on a persistent volume, with daily snapshots and one-click restore available through the Backups add-on (included on Max). See Hosted OpenClaw on Diali for what the hosting includes and Diali pricing for what it costs.

• One required file, and the frontmatter does the rest.
• Write the description for the reader deciding whether to install, not for yourself.
• The importer sees public, non-fork, own-account repositories only.