docs: document skill categories and topics (#3380)

* docs: document skill categories and topics

Add a Catalog metadata section to docs/publishing.md covering --categories
and --topics, the 14 valid category slugs, the limits ClawHub enforces, the
reserved topic names, the `other` default, and how stored values change on a
later publish. Cross-reference it from the skill publish and sync entries in
docs/cli.md.

Values read from packages/schema/src/catalogMetadata.ts,
convex/lib/skillPublish.ts, and packages/clawhub/src/cli.ts.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs: cover the CI and plugin paths for catalog metadata

Three gaps in the first pass, all the same shape as the one this PR set
out to fix -- a way to publish with no way to set catalog metadata:

The reusable skill-publish.yml workflow has no categories or topics
input. It builds the command with --owner and --tags only, so a catalog
repo publishing through CI lands every skill in `other`, exactly like
sync. The new section sat directly under the workflow snippet and said
"set both when you publish," which read as though the block above it
could. Documented in both files.

`package publish` takes the same two flag names against
PLUGIN_CATEGORY_DEFINITIONS -- a different 12-slug list documented
nowhere -- so a reader who followed the new link would try
`development` and have the publish rejected. The cli.md entry now names
the plugin slugs and says the topic rules are shared, which they are:
convex/packages.ts:8585 resolves through resolvePluginCategories but
reuses normalizeCatalogTopics.

Moved the metadata section above the catalog-repo prose so the flags sit
with the command they belong to, and gave the CI content its own
heading rather than leaving it to trail the section. No wording in the
moved block changed.

Also two enforced rules the first pass omitted: repeats are dropped
rather than rejected and are matched after normalization (so `git,Git`
is one topic, and both limits count what survives), and topics cannot
contain invisible formatting characters. Qualified the 3-category limit,
which is applied after `other` is dropped, so `other,development,
operations` stores two rather than failing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs: scope plugin-category validation to code and bundle plugins

Review caught that the package-publish bullet claimed every publish
validates --categories against the 12 plugin slugs. The claw family
does not: convex/packages.ts branches on family === "claw" and stores
the declared slugs without resolvePluginCategories, while
normalizeCatalogTopics still runs for every family. The bullet now
limits the slug check to code and bundle plugins, links docs/claws.md
for the exception, and keeps the shared-topic-rules claim, which held.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

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 <slugs>` and `--topics <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 <seconds>` sets the `--wait` deadline (default: 1800).
 - `--owner <handle>` publishes under a user or org publisher handle when the actor has publisher access.
+- `--categories <slugs>` and `--topics <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`.

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