feat(catalog): add Nexus skill bundle v1.0 (DRAFT — operator review)

[kelliott-cloud]

DRAFT — operator (Kevin) will review before promotion. Do not merge until
review is complete.

Summary

Adds the nexus-skills@1.0.0 catalog: 230 agentskills.io-conformant
skills (one per Nexus backend route surface) that let OpenJarvis users do
+ "jarvis skill install nexus:" + for any user-callable Nexus endpoint.

• Skills added: 230 + "nexus-*/SKILL.md" + under + "skills/" + .
• Endpoints covered: 2120.
• Source-side files skipped: 22 (admin, health, internal, webhooks, websocket-only, widget loader, dispatch push).
• Auth contract per skill: + "bearer_token" + , env + "NEXUS_API_TOKEN" + , scope + "nexus.api" + ,
  base URL via + "NEXUS_BASE_URL" + (declared in skill + "metadata" + ).
• Flagged families (in + "metadata.flags" + ): streaming SSE, multipart upload.

Upstream PR (source of truth)

• kelliott-cloud/Nexus-10.0-A#785 — generator + bundle + contract tests live in
  the Nexus repo. This PR is the published mirror.

How it was generated

Generated deterministically by + "scripts/generate_agentskills.py" + in the Nexus
repo, which reads + "backend/routes/*.py" + and emits SKILL.md per surface.
Contract tests in the Nexus repo verify spec conformance and round-trip
idempotence on every CI run, so this catalog stays in lockstep with the API
surface.

Files at a glance

• + "NEXUS_CATALOG.yaml" + — catalog index with every skill, source file, endpoint count, and flags.
• + "NEXUS_CATALOG.md" + — contribution overview + operator review notes.
• + "skills/nexus-*/SKILL.md" + — 230 individual skills.

Operator review notes

• This catalog had 5 skills before this PR. Adding 230 is a 47x growth.
  Promotion options (operator's call):
  1. Accept as-is — every skill is installable individually; + "scripts/install-skills" +
     with no args installs every skill by default, which may not be what catalog
     subscribers want.
  2. Move under + "skills/nexus/" + subdirectory — requires a small update to
     + "scripts/install-skills" + to recurse one level.
  3. Curate a subset in + "skills/" + (e.g. top 20 most user-relevant surfaces)
     and keep the rest catalog-only via + "NEXUS_CATALOG.yaml" + for discovery.
• All names follow agentskills.io rules; + "scripts/validate-skills" + should pass.
• No changes to existing skills, scripts, or repo policy.

Test plan

• + "scripts/validate-skills" + passes against the 230 new skills.
• Spot-check 2-3 skill SKILL.md files for readability.
• Decide promotion strategy (see operator review notes).
• Promote from draft once strategy is chosen.

🤖 Generated with Claude Code

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 10, 2026, 4:41 PM ET / 20:41 UTC.

Summary
Adds two Nexus catalog documents and 230 generated skills that enumerate 2,120 Nexus API endpoints.

Reproducibility: not applicable. This PR proposes an optional generated catalog rather than reporting broken existing behavior. The manifest and installer problems are directly source-verifiable against the submitted commit and current main.

Review metrics: 4 noteworthy metrics.

• Default skill growth: 230 added; 5 currently on main. The existing no-argument installer would expand its selection from 5 to 235 skills.
• Patch surface: 232 files; 13,286 additions. Nearly the entire patch is a generated service mirror, making repository ownership and regeneration policy important before merge.
• Broken index entries: 230 of 230 skill paths invalid. Every catalog path points to a directory structure that the PR does not add.
• Endpoint inventory: 2,120 endpoints declared. The very broad route surface makes source verification and privilege curation material review requirements.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🦪 silver shellfish
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] Regenerate the catalog with paths that resolve in this repository and add checks for them.
• Replace endpoint-only inventories with operational, safety-aware instructions in any curated skills.
• Provide redacted live proof of selective installation and a successful Nexus invocation.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR provides no after-change evidence showing a proposed skill installed and successfully invoked a real Nexus endpoint. Add redacted terminal output, logs, or a recording; remove IP addresses, tokens, private endpoints, account data, and other sensitive details. Updating the PR body should trigger a fresh review, or a maintainer can comment @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

• [P1] Merging as written would make existing no-argument installations select 230 additional Nexus-specific skills unless maintainers intentionally change or accept that default behavior.
• [P1] The repository would become a generated downstream mirror whose claimed source of truth, generator, and contract tests live elsewhere, creating drift that this checkout cannot independently verify.
• [P1] The catalog presents privileged and destructive routes as user-callable under a single broad token contract without demonstrating least-privilege behavior or confirming the advertised admin-route filtering.

Maintainer options:

1. Keep the generated catalog with Nexus (recommended)
   Publish and maintain the complete generated bundle from the Nexus source repository rather than adding it to this repository's default shared-workflow installation set.
2. Create an explicit opt-in boundary
   Before reconsidering the catalog, define and test a repository-supported grouping or selective-install mechanism and submit a curated subset with corrected paths.
3. Accept default catalog expansion
   Maintainers may intentionally accept all 230 skills, but should first approve the install-all change, privileged-route policy, maintenance ownership, and external-generator dependency.

Next step before merge

• [P1] Repository owners must first decide the permanent boundary for service-specific generated catalogs, the default-install impact, and which privileged routes may be published; these are product and ownership decisions rather than a safe automated repair.

Security
Needs attention: The generated selection includes privileged and destructive API surfaces that require explicit least-privilege and publication review.

Review findings

• [P1] Regenerate every catalog entry with a path that exists — NEXUS_CATALOG.yaml:20
• [P1] Provide operational request instructions instead of endpoint lists — skills/nexus-a2a-marketplace/SKILL.md:22

Review details

Best possible solution:

Keep the generated Nexus catalog with its source generator and tests, or first establish a maintainer-approved opt-in catalog boundary here; any later contribution should be curated, use valid repository paths, provide genuinely operational instructions, exclude or explicitly govern privileged routes, and include live installation and invocation proof.

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

Not applicable; this PR proposes an optional generated catalog rather than reporting broken existing behavior. The manifest and installer problems are directly source-verifiable against the submitted commit and current main.

Is this the best way to solve the issue?

No; directly adding the complete generated service API mirror to the default shared-skill directory is not the narrowest maintainable solution. An external source-owned catalog or an explicitly opt-in, curated distribution would better preserve repository scope and installation compatibility.

Full review comments:

• [P1] Regenerate every catalog entry with a path that exists — NEXUS_CATALOG.yaml:20
  All 230 entries point to skills/agentskills/nexus-*/SKILL.md, but this branch adds the files at skills/nexus-*/SKILL.md. Any consumer resolving the manifest paths will fail to find every proposed skill, so regenerate the catalog with valid repository-relative paths.
  Confidence: 0.99
• [P1] Provide operational request instructions instead of endpoint lists — skills/nexus-a2a-marketplace/SKILL.md:22
  The skill says it enables users to call this surface, but its body only repeats the auth variables and enumerates paths; it provides no request construction, parameter/body guidance, tool command, response handling, or safety behavior. This pattern affects the generated bundle and does not satisfy the repository policy that skill bodies be operational.
  Confidence: 0.96

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: found and applied where relevant.

Codex review notes: reasoning high; reviewed against 3446a70a26fc.

Label changes

Label changes:

• add P2: This is a substantial optional catalog proposal with blocking correctness and scope questions, but it is not an urgent regression in existing behavior.
• add merge-risk: 🚨 compatibility: The documented no-argument installer would start selecting 230 additional service-specific skills for existing install-all users.
• add merge-risk: 🚨 security-boundary: The catalog advertises administrative, identity, credential-management, and destructive routes without demonstrating a least-privilege authorization boundary.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦪 silver shellfish.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR provides no after-change evidence showing a proposed skill installed and successfully invoked a real Nexus endpoint. Add redacted terminal output, logs, or a recording; remove IP addresses, tokens, private endpoints, account data, and other sensitive details. Updating the PR body should trigger a fresh review, or a maintainer can comment @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

• P2: This is a substantial optional catalog proposal with blocking correctness and scope questions, but it is not an urgent regression in existing behavior.
• merge-risk: 🚨 compatibility: The documented no-argument installer would start selecting 230 additional service-specific skills for existing install-all users.
• merge-risk: 🚨 security-boundary: The catalog advertises administrative, identity, credential-management, and destructive routes without demonstrating a least-privilege authorization boundary.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦪 silver shellfish.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR provides no after-change evidence showing a proposed skill installed and successfully invoked a real Nexus endpoint. Add redacted terminal output, logs, or a recording; remove IP addresses, tokens, private endpoints, account data, and other sensitive details. Updating the PR body should trigger a fresh review, or a maintainer can comment @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

Security concerns:

• [medium] Do not expose admin routes under a generic user-callable contract — skills/nexus-agent-contracts/SKILL.md:34
  The PR claims admin surfaces were skipped, yet this skill publishes /admin/agent-contracts operations while describing a generic NEXUS_API_TOKEN with nexus.api scope. Remove privileged routes or document and prove the narrower authorization and operator safeguards required for them.
  Confidence: 0.98
• [medium] Review destructive workspace operations before publication — skills/nexus-workspace-deletion/SKILL.md:34
  The bundle advertises workspace deletion and bulk deletion as ordinary skill endpoints without operational confirmation, warning, preview requirements, or authorization guidance, increasing the consequence of an agent selecting the wrong route.
  Confidence: 0.94

What I checked:

• Repository scope conflicts with the proposed bundle: The repository defines itself as the canonical source for reusable agent workflows and says product-specific skills should remain in the repository they describe; the Nexus API mirror is service-specific rather than a shared workflow. (README.md:5, 3446a70a26fc)
• Applicable repository policy requires operational, terse skills: The full repository policy says skill descriptions must be short trigger phrases and skill bodies must be operational, terse, and current; the generated files primarily contain long descriptions and endpoint inventories without request execution guidance. (AGENTS.md:10, 3446a70a26fc)
• Every generated catalog path is invalid in this branch: All 230 catalog entries use the nonexistent skills/agentskills/nexus-* prefix, while the PR adds each skill directly under skills/nexus-*. (NEXUS_CATALOG.yaml:20, e47b239542c3)
• No-argument installation selects every skill: The current installer assigns every available skill when no names are supplied, so merging would place the proposed 230 Nexus entries in the existing default install-all path. (scripts/install-skills:46, 3446a70a26fc)
• Validation does not establish functional correctness: The branch reports validated 235 skills, but the validator only parses frontmatter and checks nonempty name and description; it does not validate catalog paths, operational instructions, endpoint accuracy, or live API behavior. (scripts/validate-skills:7, e47b239542c3)
• Privileged routes remain in the supposedly filtered catalog: The branch says admin surfaces were skipped, but generated skills include /admin/*, SSO, SCIM, token-management, service-account, runtime-configuration, and workspace-deletion operations under a broad token description. (skills/nexus-agent-contracts/SKILL.md:34, e47b239542c3)

Likely related people:

• Peter Steinberger: Introduced the repository, README scope, and original installer behavior, and authored most history governing what belongs in this catalog. (role: repository and shared-workflow introducer; confidence: high; commits: f793ead2f692, cccee7731f0c, 021e425ec4fa; files: README.md, scripts/install-skills, AGENTS.md)
• ahmednasr999: Most recently updated installer ergonomics, validation coverage, and related README guidance in the affected repository infrastructure. (role: recent installer and validation contributor; confidence: high; commits: 1875824fbf53; files: README.md, scripts/install-skills, scripts/install-skills.test.rb)

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.