Skip to content

docs: enumerate canonical category slugs in spec.md or docs/ #160

Description

@jdjioe5-cpu

Context

I tried to file a new runx skill against runxhq/runx and ran into a small but real docs gap: the catalog at https://runx.ai/x lists 8 categories (authoring, code, content, data, ops, payments, research, security) — verified via GET /v1/skills facets today — but spec.md and SKILL.md frontmatter docs do not enumerate the canonical category list, and the category field on the registry row is described only in passing.

This means:

  • A first-time author has no obvious way to know which category value their skill belongs to (compare with how tags is currently free-form).
  • The URL convention /x?category=<slug> (proposed in docs: add registry discoverability note — and category hints for first-time authors #145) has no canonical mapping table, so a maintainer reviewing a PR cannot tell if payments vs finance vs payouts is the right pick.
  • The spec lists the frontmatter but not the enumeration that the public registry read route uses.

Proposal (small, docs-only)

Add a one-line reference section to spec.md "Skill Format" (or a short subsection under "Registry Protocol") that:

  1. Lists the canonical category slugs the registry read route returns today.
  2. Notes that new categories must be added by a maintainer after a registry code change, not by a skill author in frontmatter.
  3. Cross-links to GET /v1/skills so the list is verifiable.

This keeps the spec small (a single short subsection, ≤ 12 lines), is purely docs, and matches the "Stable vs Draft" labeling discipline already used elsewhere in spec.md. No CLI change, no registry schema change, no new category field — just exposing what already exists.

Why this is useful for the project

  • First-time skill authors can file correct PRs on the first try without back-and-forth.
  • Reviewers get a one-line checklist to enforce before merging skill frontmatter.
  • Future maintainers adding a new category know they have to update both the registry code and this docs section.

Out of scope

If maintainers prefer, this can also live as a short "Category Canonical List" subsection under docs/ rather than in spec.md itself — happy to draft either location.

Verified category list (live, 2026-06-27):

authoring, code, content, data, ops, payments, research, security

(Sourced from https://api.runx.ai/v1/skills facets — current total field at the time of this issue is 24.)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions