docs: group skills for skills.sh

[vyctorbrzezowski]

I’m proposing collections on the ClawHub home page to improve discoverability and navigation across community skills, based on community signals. Since this is a popular skill repo, this PR proposes categorizing its skills with the skills.sh.json pattern documented at https://www.skills.sh/docs/customize, which Patrick Erichsen has already adopted in openclaw/clawhub to feed this kind of collection.

Example of where this would be used:

Adds a root skills.sh.json so skills.sh can show this repo's skills in curated sections instead of relying on the default install-sorted list.

Scope:

• groups all 48 current skills/*/SKILL.md slugs
• keeps notGrouped at bottom so future unlisted skills still appear
• does not change any skill contents or install behavior

Validation:

• parsed skills.sh.json with Node
• checked every listed slug exists and is unique
• scripts/validate-skills
• git diff --check origin/main...HEAD

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 11, 2026, 8:09 AM ET / 12:09 UTC.

Summary
Adds a root skills.sh.json with six skills.sh collection groupings and notGrouped: bottom for unlisted skills.

Reproducibility: not applicable. this is a repository display-metadata feature, not a bug report. The source-level check is high confidence: current main has 49 skills while the proposed metadata lists 48.

Review metrics: 2 noteworthy metrics.

• Changed surface: 1 file added, 90 lines. The PR is confined to static root metadata and does not touch executable code, dependencies, workflows, or skill bodies.
• Skill coverage: 48 listed, 49 current, 1 missing. The metadata is meant to group current skills, so inventory drift is the main source-level correctness check before merge.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🦐 gold shrimp
Result: blocked until real behavior proof is added.

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

Rank-up moves:

• [P1] Add maintainer-orchestrator to the intended grouping or explicitly document why it should remain ungrouped.
• [P1] Add after-fix proof for this repository's metadata, with private details redacted.
• Have the repository owner approve or adjust the public grouping taxonomy.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR has validation claims and generic example screenshots, but no after-fix proof showing this repository's metadata validating or rendering; add redacted terminal output, logs, a linked artifact, screenshot, or recording, then update the PR body to trigger review.

Risk before merge

• [P1] Merging as-is leaves maintainer-orchestrator outside the curated groups; notGrouped: bottom prevents disappearance, but the requested curated coverage is no longer complete.
• [P1] After-fix real behavior proof is still missing for this repository's metadata.
• [P1] The six group titles and memberships are public curation choices, so repository-owner approval should settle whether the taxonomy matches how these skills should be presented.

Maintainer options:

1. Decide the mitigation before merge
   Land a maintainer-approved skills.sh.json that covers all current skills, keeps fallback behavior for future skills, and includes concrete validation or rendering proof.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P1] Contributor proof and maintainer taxonomy approval are required; the code issue is narrow, but missing external proof makes this a human-only PR gate.

Security
Cleared: The diff adds static JSON metadata only; no executable path, dependency source, secret handling, or supply-chain surface is introduced.

Review findings

• [P2] Group the current maintainer-orchestrator skill — skills.sh.json:28

Review details

Best possible solution:

Land a maintainer-approved skills.sh.json that covers all current skills, keeps fallback behavior for future skills, and includes concrete validation or rendering proof.

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

Not applicable; this is a repository display-metadata feature, not a bug report. The source-level check is high confidence: current main has 49 skills while the proposed metadata lists 48.

Is this the best way to solve the issue?

No for merge as-is; a root skills.sh.json is the right implementation surface, but the branch should be refreshed to include maintainer-orchestrator and backed by real validation or rendering proof.

Full review comments:

• [P2] Group the current maintainer-orchestrator skill — skills.sh.json:28
  Current main now has skills/maintainer-orchestrator/SKILL.md, but this new metadata lists 48 skills while the repo has 49. As merged, that skill would fall to the ungrouped bottom section instead of the curated collections the PR is adding, so please add it to the intended group or otherwise account for it before merge.
  Confidence: 0.93

Overall correctness: patch is incorrect
Overall confidence: 0.87

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P3: This is a low-risk discoverability metadata improvement with no runtime behavior change.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR has validation claims and generic example screenshots, but no after-fix proof showing this repository's metadata validating or rendering; add redacted terminal output, logs, a linked artifact, screenshot, or recording, then update the PR body to trigger review.

Evidence reviewed

What I checked:

• Repository policy read: Read the full target AGENTS.MD; its skill and contributor-PR guidance informed this review, including not treating changelog absence as a blocker. (AGENTS.MD:14, ccb28e064b96)
• PR diff surface: The PR adds one root metadata file, skills.sh.json, with 90 added lines and no executable code, dependency, workflow, or skill-body changes. (skills.sh.json:1, 78c65bb22592)
• Proposed grouping parse: The proposed JSON parses with 6 groups, 48 listed skill slugs, no duplicates, and notGrouped set to bottom. (skills.sh.json:3, 78c65bb22592)
• Current-main skill inventory mismatch: Current main has 49 skills/*/SKILL.md files, but the PR lists 48 and misses maintainer-orchestrator. (skills/maintainer-orchestrator/SKILL.md:2, ccb28e064b96)
• Missing skill provenance: maintainer-orchestrator was added on current main after the PR branch base, so the branch needs a refresh before it can satisfy its all-skills grouping claim. (skills/maintainer-orchestrator/SKILL.md:2, f5dce6bbad8a)
• Current validation scope: scripts/validate-skills validates the current 49 skill front matters, but it does not validate the new skills.sh grouping metadata or prove external rendering. (scripts/validate-skills:35, ccb28e064b96)

Likely related people:

• steipete: Git history for skills/, scripts/validate-skills, and the newly added maintainer-orchestrator skill is concentrated in Peter Steinberger commits. (role: feature owner and recent area contributor; confidence: high; commits: f5dce6bbad8a, 452df18af51d, 737040cf3a19; files: skills/, skills/maintainer-orchestrator/SKILL.md, scripts/validate-skills)

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.