diff --git a/docs/cli.md b/docs/cli.md index 60a7cef7..be2c2a3c 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -192,6 +192,12 @@ Stores your API token + cached registry URL. actor has publisher access. - `--migrate-owner` moves an existing skill to `--owner` while publishing a new version. Requires admin/owner access on both publishers. +- `--categories ` and `--topics ` take comma-separated values and + set where the skill appears in browse filters. A skill first published without + `--categories` is stored as `other`; a later publish that omits the flag keeps + whatever is already stored. Valid category slugs, the limits, and the reserved + topic names are listed in + [Skill catalog metadata](./publishing.md#skill-catalog-metadata). - Owner and review behavior is explained in `docs/publishing.md`. - Publishing a skill means it is released under `MIT-0` on ClawHub. - Published skills are free to use, modify, and redistribute without attribution. @@ -215,6 +221,9 @@ same automatic patch-version behavior. Set `dry_run: true` to preview without a token. Real publishes require the `clawhub_token` secret. +The workflow has no `categories` or `topics` input, so skills first published +through it are stored as `other`, the same as `sync`. + ### `sync` - Scans the current workdir, the configured skills directory, and any @@ -233,6 +242,9 @@ Set `dry_run: true` to preview without a token. Real publishes require the actor has publisher access. - `sync` is one-way publish only. It does not install, update, download, or report install/download telemetry. +- `sync` has no `--categories` or `--topics`. Skills first published through + `sync` are stored as `other` until someone sets + [skill catalog metadata](./publishing.md#skill-catalog-metadata) on them. ```bash clawhub sync --all --dry-run @@ -669,6 +681,15 @@ clawhub publisher create opik --display-name "Opik" release is published or reaches a terminal failure state. - `--wait-timeout ` sets the `--wait` deadline (default: 1800). - `--owner ` publishes under a user or org publisher handle when the actor has publisher access. +- `--categories ` and `--topics ` behave as they do for + `skill publish`, but code-plugin and bundle-plugin categories are matched + against the plugin list, not the skill one: `channels`, `models`, `memory`, + `context`, `voice`, `media`, `web`, `tools`, `runtime`, `gateway`, + `security`, `other`. Experimental [`--family claw`](./claws.md) publishes + skip that category check and store the passed slugs as-is. The topic rules + in [Skill catalog metadata](./publishing.md#skill-catalog-metadata) — + limits, reserved names, republish behavior — apply to every family, + including `claw`. - Scoped package names must match the selected owner. See `docs/publishing.md`. - Existing flags (`--family`, `--name`, `--version`, `--source-repo`, `--source-commit`, `--source-ref`, `--source-path`) still work as overrides. - Private GitHub repos require `GITHUB_TOKEN`. diff --git a/docs/publishing.md b/docs/publishing.md index 41f572f4..aa15437a 100644 --- a/docs/publishing.md +++ b/docs/publishing.md @@ -34,6 +34,73 @@ the authenticated user. Publishing skips unchanged content. A new skill starts at `1.0.0`, and later changes automatically publish the next patch version. Pass `--version` only when you need an explicit version. +### Skill catalog metadata + +Categories place a skill in the category filters on the ClawHub skills browse +page. Topics become the filter chips offered inside a selected category. Set both +when you publish: + +```bash +clawhub skill publish ./my-skill \ + --categories development,operations \ + --topics "git,worktree,cleanup" +``` + +Both flags take comma-separated values. Categories must be slugs from this list, +matched exactly, so `Development` is rejected. Topics are free-form labels; +ClawHub stores what you pass and displays the normalized form, so `Git Worktree` +appears as `#git-worktree`. + +| Slug | Description | +| --------------- | ------------------------------------------------------------------------- | +| `integrations` | Connect services, fetch data, reconcile records, and operate APIs. | +| `automation` | Build repeatable processes, scheduled jobs, pipelines, and orchestration. | +| `research` | Search, browse, scrape, summarize, monitor, and extract web information. | +| `development` | Inspect, edit, test, build, debug, and operate codebases. | +| `productivity` | Manage tasks, calendars, email, meetings, projects, and business work. | +| `communication` | Message, publish, and operate social or communication services. | +| `creative` | Create and edit images, video, audio, music, design, and writing. | +| `knowledge` | Work with documents, notes, knowledge bases, teaching, and learning. | +| `agents` | Change how an agent plans, reflects, learns, remembers, or collaborates. | +| `operations` | Inspect, monitor, deploy, and operate local systems or infrastructure. | +| `security` | Audit, scan, authenticate, and protect systems or data. | +| `finance` | Work with payments, budgets, banking, shopping, markets, and commerce. | +| `lifestyle` | Travel, health, fitness, cooking, sports, home, and daily-life utilities. | +| `other` | Skills that do not yet fit another browse category. | + +Rules ClawHub applies to both fields: + +- A skill can carry at most 3 categories and at most 5 topics. +- An unknown category slug fails the publish. `--dry-run` does not check slugs; + the registry validates them when the publish runs. +- `other` is dropped when it is passed alongside a specific category. The + 3-category limit is applied after that, so `other,development,operations` + stores two categories rather than failing. +- Repeats are dropped rather than rejected, and they are matched after + normalization, so `git,Git` is one topic. Both limits count what is left after + that, not what you passed. +- Each topic is at most 48 characters, and topics cannot contain invisible + formatting characters. +- These topic names are reserved by ClawHub and are rejected: `approved`, + `audited`, `certified`, `clawhub`, `community`, `curated`, `endorsed`, + `featured`, `official`, `officials`, `openclaw`, `recommended`, `staff-pick`, + `trusted`, `trusted-publisher`, `verified`. The check runs on the normalized + form, so `Official` and `staff pick` are rejected too. +- A skill first published without `--categories` is stored as `other`, so it only + appears under the Other category. +- On a later publish, omitting `--categories` or `--topics` keeps the values + already stored. Pass the flag again to change them. Passing an empty value + clears the field: `--categories ""` returns the skill to `other`, and + `--topics ""` removes its topics. +- Passing either flag publishes even when the files have not changed, so fixing + metadata this way creates a new patch version. + +Skill owners can also edit categories and topics from the skill's settings page +on ClawHub. That is the quickest fix for a skill that was already published into +`other`. + +### Publishing from a catalog repo + For catalog repos, use ClawHub's reusable [`skill-publish.yml` workflow](https://github.com/openclaw/clawhub/blob/main/.github/workflows/skill-publish.yml). It calls `skill publish` for each immediate skill folder under `root` (default: @@ -52,6 +119,12 @@ jobs: Use `dry_run: true` to preview new and changed skills without publishing. +The workflow has no `categories` or `topics` input. It calls `skill publish` +with `--owner` and `--tags` only, so skills first published through it are +stored as `other`, the same as [`clawhub sync`](./cli.md#sync). Set catalog +metadata on those skills from the skill's settings page, or publish once from +the CLI with `--categories`. + ## Plugins Plugins use npm-style package names. Scoped package names include the owner in