Add nexus-tool-builder skill + nexus-tool-auditor agent

[mike-hanono]

Summary

Adds a shareable Claude Code skill that automates Nexus tool creation, plus an auditor sub-agent that scores generated crates against an authoritative security checklist. Everything is additive under .claude/ — no existing files touched, no behavior change to current tools.

This is PR 1 of 2. PR 2 (payments-stripe tool) is stacked on top of this one and exercises the skill end-to-end.

What this adds

• .claude/skills/nexus-tool-builder/

  • SKILL.md — entry point with the full skill workflow (off-chain Rust and on-chain Move paths, pre-flight checks, hard rules).
  • reference/ — authoritative material the skill loads on demand:
    • architecture.md — canonical tool-crate layout
    • interface.md — NexusTool trait + bootstrap! semantics
    • style-guide.md — port naming, error variants, flatness rules
    • onchain-tools.md — Move-tool variant (ProofOfUID, witness, TaggedOutput)
    • hosting-options.md — GCP Cloud Run as v1 default; DePIN deferred
    • security-checklist.md — authoritative C1–C11 / H1–H10 / M1–M6 / Move C-M1–C-M6 / H-M1–H-M6 / cross-cutting checks
    • faq.md — common pitfalls (top-level oneOf, dedup paths, workspace deps)
  • templates/rust/ — Cargo.toml, README, main.rs, error.rs, stateless client.rs, endpoint.rs, models.rs, tools_mod.rs
  • templates/move/ — Move.toml + sources/tool.move.tmpl
  • templates/deploy/ — Dockerfile, Cloud Run testnet/mainnet YAML, register.sh, GitHub Actions workflows for testnet (push to main) and mainnet (tag, gated on testnet green)
  • scripts/new_tool.sh — wraps nexus tool new, moves into tools/
  • scripts/verify.sh — cargo check / clippy -D warnings / test / fmt --check / live /health + /meta smoke
  • scripts/audit.sh — mechanical static + dynamic checks (cargo toolchain, greps for unwrap/expect/panic in non-test code, env-var credential reads, statefulness sniff, sk_live_ leak, Cloud Run secret mounts that don't match the allowed set)

• .claude/agents/nexus-tool-auditor.md

  • Sub-agent triggered after verify.sh (or invoked manually with Agent({ subagent_type: "nexus-tool-auditor", ... })).
  • Reads reference/security-checklist.md as source of truth.
  • For off-chain: runs audit.sh, fuzzes /invoke with malformed payloads, optionally backtests against fixtures/, writes tools/<crate>/AUDIT.md with severity-graded findings + sign-off recommendation.
  • For on-chain: also checks witness stamping on every code path, missing AdminCap guards, copyable witness, hardcoded addresses, gas-grief loops.
  • Refuses to mark mainnet-ready while any CRITICAL is open.

Credential model (baked into templates)

The skill's templates enforce the same per-request credential model used today by tools/llm-openai-chat-completion and tools/social-twitter: upstream API credentials live ONLY in the Input struct, never in env vars, never on disk, never in Cloud Run secrets. The Cloud Run YAML templates mount only the Tool's own Ed25519 signing key and the allowed-leaders list. The audit script's checks C7, C9, C10, C11 enforce this mechanically.

The relevant section of the security checklist:

| C7 | Tool source MUST NOT read any upstream-API credential from env vars, disk, or any persistent store. Credentials live ONLY in Input struct fields. |
| C8 | Tool MUST NOT log, print, format-debug, or include in Output::Err::reason any value of a credential field on Input. |
| C9 | Tool MUST be stateless across invocations. |
| C10 | Tool MUST NOT mount upstream API keys as Cloud Run secrets. |
| C11 | The crate's README.md and any example DAG JSON MUST NOT contain credential-shaped values. |

How a contributor uses this

# inside nexus-tools/ checkout
# (skill auto-loads in any Claude Code session run from this repo)

# from your AI assistant:
> create a Nexus tool for the Stripe API

The skill walks the contributor through endpoint discovery, generates the crate per the templates above, runs verify.sh, then calls the auditor. PR 2 of 2 is the artifact of running this against Stripe.

Test plan

• Skill files lint cleanly (bash -n, YAML parse, JSON parse) — verified locally
• SKILL.md frontmatter is valid YAML
• Templates render against the live nexus tool new --template rust scaffold (verified by PR 2)
• scripts/audit.sh produces a clean run on a known-good crate (verified by PR 2)
• After merge, any team member can trigger the skill in Claude Code with no extra setup

🤖 Generated with Claude Code