Skill folder format: required files, artifacts, and limits

Skill format

On disk

A skill is represented as a directory.

Required:

• SKILL.md (or skill.md; the older skills.md format is still valid)

Optional:

• any additional regular files (refer to “Skill files”)
• .clawhubignore (patterns to exclude during publishing; the older format is .clawdhubignore)
• .gitignore (also recognised)

GitHub import

The GitHub web importer applies stricter rules than local publish or sync. It only picks up SKILL.md or the older skills.md format from public repositories that are not forks and belong to the currently logged-in GitHub account. Private repositories, forks, archived or disabled repos, and public repos owned by others are not imported.

Metadata written locally by the CLI during installation:

• <skill>/.clawhub/origin.json (the older format is .clawdhub)

State recorded by the CLI for the working directory:

• <workdir>/.clawhub/lock.json (the older format is .clawdhub)

SKILL.md

• Markdown content, optionally preceded by YAML frontmatter.
• The server reads metadata from the frontmatter at publish time.
• description becomes the skill's summary in the user interface and search results.

For portable Agent Skills, name must match the parent directory name and contain 1, 64 lowercase letters, digits, or hyphens. ClawHub keeps the routable slug and the display name in the catalog separate, so names created by other clients remain publishable and are never silently changed. Long names in catalog listings may be truncated visually without affecting the stored value.

Frontmatter metadata

Skill metadata lives in the YAML frontmatter at the beginning of your SKILL.md. This tells the registry and the security scanner what the skill needs to operate.

Basic frontmatter

---
name: my-skill
description: Short summary of what this skill does.
version: 1.0.0
---

Runtime metadata (metadata.openclaw)

Define your skill's runtime dependencies under metadata.openclaw (also known as metadata.clawdbot or metadata.clawdis).

---
name: my-skill
description: Manage tasks via the Todoist API.
metadata:
  openclaw:
    requires:
      env:
        - TODOIST_API_KEY
      bins:
        - curl
    primaryEnv: TODOIST_API_KEY
---

Use requires.env to list environment variables that must exist before the skill starts. Use envVars when you need individual metadata for each variable, including optional ones with required: false.

Full field reference

Install specs

When your skill needs dependencies to be installed, list them in the install array:

metadata:
  openclaw:
    install:
      - kind: brew
        formula: jq
        bins: [jq]
      - kind: node
        package: typescript
        bins: [tsc]

Installation types that are supported: brew, node, go, uv.

Optional environment variables

Define optional environment variables under metadata.openclaw.envVars and assign required: false. Do not place optional entries inside requires.env, because requires.env indicates the skill cannot function without them.

metadata:
  openclaw:
    primaryEnv: TODOIST_API_KEY
    envVars:
      - name: TODOIST_API_KEY
        required: true
        description: Todoist API token used for authenticated requests.
      - name: TODOIST_PROJECT_ID
        required: false
        description: Optional default project ID when the user does not specify one.

Why this matters

ClawHub's security analysis verifies that the declarations in your skill match its actual behavior. If your code refers to TODOIST_API_KEY but the frontmatter does not list it under requires.env, primaryEnv, or envVars, the analysis flags a metadata inconsistency. Keeping your declarations accurate helps the skill pass review and makes clear to users what they are installing.

Example: complete frontmatter

---
name: todoist-cli
description: Manage Todoist tasks, projects, and labels from the command line.
version: 1.2.0
metadata:
  openclaw:
    requires:
      env:
        - TODOIST_API_KEY
      bins:
        - curl
    primaryEnv: TODOIST_API_KEY
    envVars:
      - name: TODOIST_API_KEY
        required: true
        description: Todoist API token.
      - name: TODOIST_PROJECT_ID
        required: false
        description: Optional default project ID.
    emoji: "\u2705"
    homepage: https://github.com/example/todoist-cli
---

Skill files

Publish accepts every regular file inside the skill folder, no matter the extension. Ignore files, hidden paths, symlinks, macOS metadata, and server-side size limits still apply.

• Bounded files with valid UTF-8 content can be previewed as escaped plain text and are part of bounded text analysis.
• Other files keep their original bytes and can be downloaded.
• Security scanners receive the complete stored artifact; text detection is a rendering and analysis concern, not an upload allowlist.

Limits (server-side):

• Total bundle size: 50MB.
• Embedding text includes SKILL.md plus roughly 40 bounded UTF-8 files (best-effort cap).

Slugs

• Default name comes from the folder name.
• Package scopes must match the ClawHub publisher handle exactly. Publisher handles may use lowercase letters, numbers, hyphens, dots, and underscores; they must start and end with a lowercase letter or number.
• Package slugs must be lowercase and npm-safe, for example @example.tools/demo-plugin or demo-plugin.

Versioning + tags

• A fresh version is produced with every publish, following semantic versioning.
• Tags act as named references that point to a specific version; latest is the typical choice for this purpose.

License

• The MIT-0 license applies to every skill that gets published on ClawHub.
• Any user can copy, alter, and share published skills, even for commercial use.
• Giving credit to the original author is not mandatory.
• Refrain from placing conflicting license terms inside SKILL.md; ClawHub does not allow individual skills to override the default license.

Paid skills

• Paid skills, individual skill pricing, paywalls, and revenue sharing are not supported on ClawHub.
• Avoid inserting pricing metadata into SKILL.md; the skill format does not include this field, and doing so will not turn a published skill into a paid one.
• When your skill depends on a paid external service, clearly explain the third-party cost and necessary account within the skill's instructions and environment declarations (use requires.env for mandatory variables, or envVars combined with required: false for optional ones).