You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 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:
Lists the canonical category slugs the registry read route returns today.
Notes that new categories must be added by a maintainer after a registry code change, not by a skill author in frontmatter.
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
No change to the registry row schema.
No change to the frontmatter category field (already free-form today).
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.
Context
I tried to file a new runx skill against
runxhq/runxand 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 viaGET /v1/skillsfacets today — butspec.mdandSKILL.mdfrontmatter docs do not enumerate the canonical category list, and thecategoryfield on the registry row is described only in passing.This means:
categoryvalue their skill belongs to (compare with howtagsis currently free-form)./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 ifpaymentsvsfinancevspayoutsis the right pick.Proposal (small, docs-only)
Add a one-line reference section to
spec.md"Skill Format" (or a short subsection under "Registry Protocol") that:GET /v1/skillsso 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 newcategoryfield — just exposing what already exists.Why this is useful for the project
Out of scope
categoryfield (already free-form today).If maintainers prefer, this can also live as a short "Category Canonical List" subsection under
docs/rather than inspec.mditself — happy to draft either location.Verified category list (live, 2026-06-27):
(Sourced from
https://api.runx.ai/v1/skillsfacets — currenttotalfield at the time of this issue is 24.)