docs: group skills for skills.sh

[vyctorbrzezowski]

Adds a root skills.sh.json so the skills.sh repository page can render this catalog in six curated sections instead of one install-sorted list. ClawHub's GitHub-backed publisher catalog uses the same manifest shape when a repository is configured as a source.

Scope:

• groups all 49 current remotely discoverable skills/*/SKILL.md slugs
• includes the newer maintainer-orchestrator skill under GitHub & OpenClaw
• keeps notGrouped at bottom so future unlisted skills remain visible
• does not change skill contents or CLI install behavior
• excludes nine tracked symlink entries because a fresh remote checkout does not contain their external target repositories and the skills CLI does not discover them

Consumer proof:

• npx -y skills@1.5.11 add steipete/agent-scripts --list cloned the public repository and found 49 skills, including maintainer-orchestrator.
• A synthetic merge tree (origin/main plus this manifest) passed the same CLI path with 49 skills.
• Current ClawHub consumer code at e86aa30a77aa130bfdc10e65885d0623cc1db4f2 accepted the synthetic merge through buildGitHubSkillSourceSnapshot and buildGitHubSkillCatalogDisplay: manifest status ok, 49 discovered, section counts 6/9/9/6/9/10, 49 rendered, zero Other skills entries.
• ClawHub parser: https://github.com/openclaw/clawhub/blob/e86aa30a77aa130bfdc10e65885d0623cc1db4f2/convex/lib/githubSkillSync.ts
• ClawHub catalog renderer: https://github.com/openclaw/clawhub/blob/e86aa30a77aa130bfdc10e65885d0623cc1db4f2/convex/lib/publisherCatalogDisplay.ts
• skills.sh behavior and schema: https://www.skills.sh/docs/customize and https://skills.sh/schemas/skills.sh.schema.json

Validation:

• uvx check-jsonschema --schemafile https://skills.sh/schemas/skills.sh.schema.json skills.sh.json
• inventory comparison: 49 current remote skills, 49 grouped, no missing, unknown, or duplicate entries
• scripts/validate-skills
• hooks/pre-commit
• repository CI smoke commands from .github/workflows/ci.yml
• git diff --check origin/main...HEAD
• autoreview, local and full branch: no accepted/actionable findings

Owner product choice:

• The six public group names and memberships are subjective repository taxonomy and still need Peter's endorsement.
• The live skills.sh page currently retains five historical slugs no longer present in the repository (1password, brave-search, codex-review, parallels-vm, sonos-debug). This manifest intentionally describes the canonical current 49-skill inventory; those historical records may remain under Other skills. Encoding stale telemetry aliases in repository metadata is not recommended.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 13, 2026, 5:35 PM ET / 21:35 UTC.

Summary
Adds a root skills.sh.json catalog manifest that groups all 49 current discoverable skills into six skills.sh sections with ungrouped skills shown at the bottom.

Reproducibility: not applicable. This PR adds repository display metadata rather than fixing a reproducible bug. Source checks verify the manifest inventory, and the PR body now supplies real consumer proof for the synthetic merge.

Review metrics: 2 noteworthy metrics.

• Changed surface: 1 file added, 91 lines. The patch is isolated to declarative catalog metadata, so taxonomy approval matters more than runtime regression risk.
• Catalog coverage: 6 groups, 49 grouped skills, 9 symlink entries excluded. The grouped list matches current real skill directories while intentionally leaving externally targeted symlinks out of the remote catalog.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P2] Have Peter approve or adjust the public group names and memberships before merge.

Risk before merge

• [P1] Merging publishes subjective group titles and memberships as this repository's public skills taxonomy, which CI cannot validate as the intended owner curation.
• [P1] The live skills.sh page may still show historical slugs or cached telemetry under an ungrouped section; maintainers need to accept the PR body's current-inventory-only choice.

Maintainer options:

1. Approve the public taxonomy
   Peter can approve the six groups as repository-owned public curation, then merge the current-inventory-only manifest.
2. Revise grouping before merge
   If any section names or memberships need different public framing, update skills.sh.json and re-check the 49-skill inventory before merge.
3. Pause if repo-level grouping is not wanted
   If maintainers do not want skills.sh-specific public curation in this personal repo, leave the PR open for discussion or close it without landing the manifest.

Next step before merge

• [P2] Human review remains because the only blocker is public taxonomy/product approval, not an automated code repair.

Security
Cleared: The diff adds static JSON metadata only and introduces no code execution, dependency, permission, credential, workflow, or supply-chain change.

Review details

Best possible solution:

Land this root manifest after Peter approves or edits the six section names and memberships, preserving the current-inventory-only approach unless legacy aliases should be encoded.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this PR adds repository display metadata rather than fixing a reproducible bug. Source checks verify the manifest inventory, and the PR body now supplies real consumer proof for the synthetic merge.

Is this the best way to solve the issue?

Yes, conditionally: a root skills.sh.json is the supported, narrow way to group skills.sh repository pages. The remaining question is owner approval of the public section names and memberships.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against a3026aea93b9.

Label changes

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. The updated PR body includes copied live CLI and ClawHub consumer results for this repository's 49-skill synthetic merge, and the owner comment points to that proof.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🦞 diamond lobster.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The updated PR body includes copied live CLI and ClawHub consumer results for this repository's 49-skill synthetic merge, and the owner comment points to that proof.
• remove rating: 🧂 unranked krab: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
• remove status: 📣 needs proof: Current PR status label is status: 👀 ready for maintainer look.

Label justifications:

• P3: This is low-risk repository catalog/discoverability metadata rather than an urgent runtime or workflow regression.
• merge-risk: 🚨 other: The remaining merge risk is public repository taxonomy and owner endorsement, which normal CI and schema checks cannot settle.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The updated PR body includes copied live CLI and ClawHub consumer results for this repository's 49-skill synthetic merge, and the owner comment points to that proof.
• proof: sufficient: Contributor real behavior proof is sufficient. The updated PR body includes copied live CLI and ClawHub consumer results for this repository's 49-skill synthetic merge, and the owner comment points to that proof.

Evidence reviewed

What I checked:

• Repository policy read: Target AGENTS.MD was read fully; it treats skills as canonical workflow surface and keeps skill edits terse, making this public taxonomy a repository-owned review decision. (AGENTS.MD:14, a3026aea93b9)
• PR diff surface: The PR adds one static root JSON file with $schema, notGrouped: bottom, and six grouping sections; it does not change skills, scripts, dependencies, or workflows. (skills.sh.json:1, 0323c097b489)
• Catalog coverage: The proposed manifest has 6 groups, 49 grouped entries, 49 unique entries, and section counts 6/9/9/6/9/10; comparison against current skills/*/SKILL.md paths produced no missing or extra slugs. (skills.sh.json:4, 0323c097b489)
• Current inventory shape: Current main has 49 real skill directories with SKILL.md and 9 tracked top-level symlink entries, matching the PR body's choice to group real remote-discoverable skills and exclude symlinks. (skills, a3026aea93b9)
• External schema compatibility: The current skills.sh schema documents a root skills.sh.json file with required groupings, optional $schema, and optional notGrouped values of top or bottom, matching the added file shape.
• Consumer proof updated: The PR body now reports exact CLI and ClawHub consumer checks for the synthetic merge tree, and the owner re-review comment explicitly says the body contains 49-skill inventory results plus exercised parser/catalog-renderer proof. (0323c097b489)

Likely related people:

• steipete: Peter Steinberger is the dominant current-main contributor for skills/, authored the skills README/validator history sampled here, added the newer maintainer-orchestrator skill, and force-pushed the latest PR head adjustment. (role: repository owner and recent skill-surface contributor; confidence: high; commits: 8c43861d74fd, f5dce6bbad8a, a3026aea93b9; files: README.md, scripts/validate-skills, skills/maintainer-orchestrator/SKILL.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[steipete]

@clawsweeper re-review

The PR body now contains exact 49-skill inventory results, current skills CLI output, and an exercised ClawHub parser/catalog-renderer proof against the synthetic merge tree.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27479674998
• Updated: 2026-06-13T21:35:38.726Z