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 5, 2026, 2:52 PM ET / 18:52 UTC.

Summary
Adds a root skills.sh.json that groups all 48 current skills/*/SKILL.md slugs into six skills.sh/ClawHub collections and keeps future unlisted skills at the bottom.

Reproducibility: not applicable. this is a repository display-metadata feature, not a bug report. I verified source-level consistency by matching the proposed 48 slugs against current skills/*/SKILL.md.

Review metrics: 2 noteworthy metrics.

• Changed surface: 1 file added, 90 lines. The PR is confined to root skills.sh display metadata and does not touch executable code, dependencies, or skill bodies.
• Skill coverage: 48 listed, 0 missing, 0 extra, 0 duplicates. The grouping matches the current skills/*/SKILL.md inventory, which is the main correctness check for this metadata.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
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 after-fix proof, such as a screenshot/recording of the skills.sh or ClawHub rendering for this repo, or copied live terminal output showing the schema and slug validation run.
• [P1] Have a maintainer approve or adjust the six public grouping titles and memberships before merge.

Proof guidance:

• [P1] Needs real behavior proof before merge: Missing: the PR has validation claims and generic example screenshots, but no after-fix proof for this repo's metadata; the contributor should add a screenshot/recording or copied live terminal output, redact private data, and update the PR body to trigger a fresh review.

Risk before merge

• [P1] After-fix real behavior proof is missing: the PR includes validation claims and generic example screenshots, but no copied live output or screenshot showing this repository's proposed metadata working.
• [P1] The six collection names and memberships are public curation choices for the repo, so maintainer approval should settle whether this taxonomy matches how the skills should be presented.

Maintainer options:

1. Decide the mitigation before merge
   Land a maintainer-approved root skills.sh.json after the contributor adds concrete proof that the metadata validates or renders for this repo, while keeping the individual skill contents unchanged.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P1] Needs maintainer approval of the public grouping taxonomy and contributor proof; there is no narrow code defect for an automated repair lane.

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

Review details

Best possible solution:

Land a maintainer-approved root skills.sh.json after the contributor adds concrete proof that the metadata validates or renders for this repo, while keeping the individual skill contents unchanged.

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

Not applicable; this is a repository display-metadata feature, not a bug report. I verified source-level consistency by matching the proposed 48 slugs against current skills/*/SKILL.md.

Is this the best way to solve the issue?

Yes for the implementation path: a root skills.sh.json is the expected metadata file and the proposed content matches current slugs. The remaining decisions are maintainer approval of the grouping taxonomy and contributor proof of the real rendered or validated result.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 09f2963703a8.

Label changes

Label changes:

• add P3: This is a low-risk discoverability/metadata improvement with no runtime behavior change.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: Missing: the PR has validation claims and generic example screenshots, but no after-fix proof for this repo's metadata; the contributor should add a screenshot/recording or copied live terminal output, redact private data, and update the PR body to trigger a fresh review.

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 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: Missing: the PR has validation claims and generic example screenshots, but no after-fix proof for this repo's metadata; the contributor should add a screenshot/recording or copied live terminal output, redact private data, and update the PR body to trigger a fresh review.

Evidence reviewed

What I checked:

• Repository policy read: Read the full target AGENTS.MD; its skills and contributor-PR guidance informed the review, and this metadata-only PR does not violate a concrete repository policy. (AGENTS.MD:13, 09f2963703a8)
• PR surface: The GitHub API reports one added file, skills.sh.json, with 90 additions and no changes to skill contents, scripts, dependencies, or install behavior. (skills.sh.json:1, 78c65bb22592)
• skills.sh schema fit: The fetched schema describes root skills.sh.json as repo-page configuration, and the proposed file uses the expected notGrouped and groupings structure; the public docs also expose skills.sh as the relevant skill-discovery surface. citeturn0search0. (skills.sh.json:1, 78c65bb22592)
• Slug coverage: The proposed grouping lists 48 skills, with 0 duplicate slugs, 0 current-main skills missing, and 0 extra slugs not present under skills/*/SKILL.md. (skills.sh.json:7, 78c65bb22592)
• Current main state: Current main has no root skills.sh.json, so the requested display metadata is not already implemented on main. (skills.sh.json, 09f2963703a8)
• Validation surface: scripts/validate-skills currently validates skills/*/SKILL.md front matter and required fields, so it supports the PR body's skill inventory claim but does not itself validate the new skills.sh grouping schema. (scripts/validate-skills:1, 09f2963703a8)

Likely related people:

• steipete: The target repo is owned by steipete, and git history for the skills, validation script, README, and AGENTS policy surface is concentrated in Peter Steinberger commits. (role: feature owner and recent area contributor; confidence: high; commits: 09f2963703a8, 737040cf3a19, 3890ba79733f; files: skills/, scripts/validate-skills, README.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.