docs: improve starter skill discovery and published links

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Curated skills.sh groups put Research, Test, and Refactor first, followed by
+  the rest of the current 34-skill catalog. Ungrouped historical entries remain
+  below the current skills; this changes discovery, not installation behavior.
+
+### Fixed
+
+- Skill catalog, schema, and setup links resolve to their repository sources
+  from the published documentation site, restoring its strict build check.
+
 ## [3.7.0] - 2026-09-13
 
 AgentOps 3.7 makes native coding the default: accepted intent, implementation

docs/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Curated skills.sh groups put Research, Test, and Refactor first, followed by
+  the rest of the current 34-skill catalog. Ungrouped historical entries remain
+  below the current skills; this changes discovery, not installation behavior.
+
+### Fixed
+
+- Skill catalog, schema, and setup links resolve to their repository sources
+  from the published documentation site, restoring its strict build check.
+
 ## [3.7.0] - 2026-09-13
 
 AgentOps 3.7 makes native coding the default: accepted intent, implementation

docs/_hooks/gen_skill_pages.py

@@ -121,9 +121,9 @@ def emit_detail(skill: dict[str, str]) -> None:
         lambda m: f"(https://github.com/boshu2/agentops/blob/main/skills/{skill['slug']}/references/{m.group(1)})",
         body,
     )
-    # Rewrite other same-skill relative paths (e.g., scripts/, templates/) the same way.
+    # Rewrite other same-skill relative paths (e.g., scripts/, schemas/) the same way.
     body = re.sub(
-        r"\((scripts|templates|fixtures|examples)/([^)]+)\)",
+        r"\((scripts|templates|fixtures|examples|schemas)/([^)]+)\)",
         lambda m: f"(https://github.com/boshu2/agentops/blob/main/skills/{skill['slug']}/{m.group(1)}/{m.group(2)})",
         body,
     )

docs/agent-workflow-reference.md

@@ -33,7 +33,7 @@ No new scheduler, command or process ledger is needed. The grandfathered pure
 fixed-dispatch adapter is separately described in its own reference.
 Optional context-budget tooling (an opt-in read-budget hook plus bulk-read /
 code-write delegation) is described in
-[context-budget delegation](../skills/agent-native/references/context-budget-delegation.md).
+[context-budget delegation](https://github.com/boshu2/agentops/blob/main/skills/agent-native/references/context-budget-delegation.md).
 
 For exact intent snapshots, subject manifests, evidence storage, scope and
 freshness, use [RPI traversal](architecture/rpi-traversal.md) and

docs/releases/2026-09-13-v3.7.0-notes.md

@@ -19,7 +19,7 @@ migration guidance below is part of the upgrade.
 - Replace `ao eval` and `ao redact` automation before updating the binary. Use your repository's evaluator and the owner's disclosure-review process. Generic `ao provenance` can retain factual evidence but does not run either retired service.
 - Replace `workflows/rpi.js` calls with native execution or an explicitly selected RPI skill invocation. The scripted retry machinery has been removed. Trackers, Git, scheduling and delivery remain under their existing owners.
 - Update managed plugins through their runtime. For source links, update the canonical checkout, inspect retired names, and relink the surviving skills you selected. `ao skills link --skill NAME` can be repeated; without selectors it links the full menu. It does not remove foreign entries or uninstall previously selected skills.
-- Codex role resources ship in the skill bundle, but installing the plugin alone does not register them. From a checkout, run `bash scripts/install-codex-context-agents.sh` for personal configuration or add `--project`, then restart Codex. See [Codex installation](../../.codex/INSTALL.md) for prerequisites and separate hook setup.
+- Codex role resources ship in the skill bundle, but installing the plugin alone does not register them. From a checkout, run `bash scripts/install-codex-context-agents.sh` for personal configuration or add `--project`, then restart Codex. See [Codex installation](https://github.com/boshu2/agentops/blob/main/.codex/INSTALL.md) for prerequisites and separate hook setup.
 - Read-budget guards remain disabled until explicitly installed. The Claude and Codex installers preserve existing settings and backups. Codex hook definitions still need review/trust in its native hook manager; linked-worktree hook installation has documented restrictions.
 - Preserve existing `.agents/` evidence. New CDLC proof uses a caller-selected protected external non-Git destination. A missing route is a failure, not permission to fall back to repository storage. `ao init` remains an optional local setup command and is not required for native work.
 - Builds use the Go 1.27.1 toolchain; `cli/go.mod` retains a Go 1.26.0 language floor. Older installations download the selected toolchain or fail according to `GOTOOLCHAIN`. CI and maintained Python checks use Python 3.14.

scripts/generate-skill-mesh.py

@@ -167,7 +167,7 @@ def router(entries: list[dict[str, Any]]) -> str:
         lines += [f"## {heading}", "", "| Skill | Use it for |", "|---|---|"]
         for entry in members:
             description = entry["description"].replace("|", "\\|").replace("\n", " ")
-            lines.append(f"| [{entry['name']}](../skills/{entry['name']}/SKILL.md) | {description} |")
+            lines.append(f"| [{entry['name']}](https://github.com/boshu2/agentops/blob/main/skills/{entry['name']}/SKILL.md) | {description} |")
         lines.append("")
     lines += ["## Complete inventory", "", md_table(entries), ""]
     return "\n".join(lines)

skills.sh.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://skills.sh/schemas/skills.sh.schema.json",
+  "notGrouped": "bottom",
+  "groupings": [
+    {
+      "title": "Start here",
+      "description": "Trace a behavior, cover a regression, or simplify code. Use one skill for the task in front of you; no new workflow or ao CLI is required.",
+      "skills": ["research", "test", "refactor"]
+    },
+    {
+      "title": "Build and review",
+      "description": "Clarify a change, implement it, and check the result. Choose these independently; Validate requires the ao CLI.",
+      "skills": ["plan", "implement", "validate", "doc", "domain", "security", "reality-check"]
+    },
+    {
+      "title": "Explore and learn",
+      "description": "Compare ideas and retrieve relevant context when it can help the current task.",
+      "skills": ["idea-genie", "reverse-engineer", "memory", "cass", "ms"]
+    },
+    {
+      "title": "Deliberate workflows",
+      "description": "Select a review strategy, the RPI charter, goal planning, or skill authoring and evaluation when the task calls for it.",
+      "skills": ["premortem", "council", "postmortem", "rpi", "craft-goal", "skill-builder", "skill-eval"]
+    },
+    {
+      "title": "Optional tool adapters",
+      "description": "Use these only with the corresponding runtime or tool. They are not prerequisites for the starter skills.",
+      "skills": ["agent-native", "codex-exec", "agy-native", "ntm", "agent-mail", "using-gc", "using-flywheel", "cc-hooks", "dcg", "rch", "sbh", "account-rotation"]
+    }
+  ]
+}