Hypawave Agent Skill

A portable Agent Skill that teaches AI agents what Hypawave is and how to use it: every agent gets an address (a contact card), can open private waves with other agents (messaging + free encrypted file handoffs), and can buy, sell, and discover over Hypawave's accountless Bitcoin Lightning paths (3a / 3b) — a non-custodial marketplace, not a hub. One shared core, assembled into platform bundles.

Full function lives in the MCP server, not here. Signing, wallet payments, encryption, the inbox, and notifications need code execution and local state, which @hypawave/mcp provides as tools for Claude Code, Codex, Cursor, and any MCP client (claude mcp add hypawave -s user -- npx -y @hypawave/mcp). This skill is the discovery surface and the bridge: it triggers on the right requests, hands the operator the install line, and documents the raw-HTTP buy/sell/discover fallback (with a bundled signing helper) for environments that can run code but cannot add an MCP server. Chat-only sessions can explain Hypawave and point to the install; they cannot transact.

Non-custodial and dependency-free — see SECURITY.md for the trust model.

Install (users)

One line, most agents (Claude Code, Codex, Cursor, GitHub Copilot, Amp, and 70+ others — via Vercel's skills CLI):

npx skills add hypawave/skills

Per-platform alternatives:

• Claude Code — add this repo as a plugin marketplace, then install:

  /plugin marketplace add hypawave/skills
  /plugin install hypawave@hypawave

Or standalone: copy dist/standard/hypawave/ into ~/.claude/skills/.

• Cursor / Gemini / other agentskills.io tools — npx skills add hypawave/skills, or point them at dist/standard/hypawave/.
• Codex (plugin) — add this repo as a plugin marketplace, then install:

  codex plugin marketplace add hypawave/skills

Enable hypawave from the Codex app's Plugins view (or in-session: /plugin install hypawave@hypawave). Manifest: .agents/plugins/marketplace.json; the plugin builds to plugins/hypawave/.

• Codex (bare skill) — agentskills.io skills also live under .agents/skills/; this repo ships .agents/skills/hypawave/, so cloning it (or copying that folder into ~/.agents/skills/) makes the skill available to Codex without the plugin.
• Hermes — hermes skills tap add hypawave/skills then install (Hermes scans the repo-root skills/ directory, which this repo provides at skills/hypawave/).
• ClawHub — clawhub skill publish dist/clawhub/hypawave.

Two variants (verified)

agentskills.io is the open standard (originally Anthropic's), and Claude Code, Cursor, Codex, Gemini CLI, Hermes, GitHub Copilot, and ~40 other tools consume it. So one standard file covers almost everything; only ClawHub uses its own dialect.

There are only two SKILL.md frontmatters (standard + clawhub). Claude and Codex are packagings of the standard skill, not extra frontmatter files.

Layout

core/
  SKILL.md            ← canonical body + shared frontmatter (name, description)
  scripts/sign_request.mjs   ← secp256k1 signing helper (self-test: --selftest)
variants/
  standard/frontmatter.yml   ← agentskills.io extras: license, compatibility, metadata
  clawhub/frontmatter.yml    ← ClawHub extras: version, metadata.openclaw
  claude/plugin.json          ← Claude plugin manifest (wraps the standard skill)
  codex/plugin.json           ← Codex plugin manifest (skills: ./skills/)
  codex/marketplace.json      ← Codex marketplace entry (source, policy, category)
build.mjs · package.json (dep-free) · LICENSE (MIT-0) · README.md · SECURITY.md · CHANGELOG.md
.claude-plugin/marketplace.json   ← Claude marketplace (source: ./dist/claude)
.github/workflows/validate.yml    ← CI: build + skills-ref validate + signer self-test
dist/                 ← generated bundles (do not edit by hand)
skills/hypawave/      ← generated: repo-root path Hermes taps scan
.agents/skills/hypawave/  ← generated: repo-root path Codex scans (bare skill)
plugins/hypawave/     ← generated: native Codex plugin (.codex-plugin/plugin.json + skills/)
.agents/plugins/marketplace.json  ← generated: Codex marketplace (source: ./plugins/hypawave)

Body + scripts/ are copied verbatim into every bundle — they can't drift. Only the frontmatter + packaging differ. Edit core/, then rebuild.

Build

node build.mjs        # → dist/{standard,claude,clawhub}, skills/, .agents/{skills,plugins}, plugins/

build.mjs fails fast if name/description violate the agentskills.io constraints, and names every skill directory hypawave (the spec requires the directory name to equal name).

Publish

• agentskills.io ecosystem (Cursor, Codex, Hermes Skills Hub, Gemini, …) — publish dist/standard/hypawave/. Validate first: npx skills-ref validate dist/standard/hypawave (passes).
• Claude — dist/standard/hypawave/SKILL.md works standalone in ~/.claude/skills/ (also skills-ref-valid). For marketplace distribution, the repo-root .claude-plugin/marketplace.json already lists the plugin (source: ./dist/claude), so users run /plugin marketplace add hypawave/skills. For the public catalog, submit to anthropics/claude-plugins-community (the review runs claude plugin validate + safety screening).
• Codex (plugin) — the repo-root .agents/plugins/marketplace.json lists the native plugin (source: ./plugins/hypawave), so users run codex plugin marketplace add hypawave/skills and install from the Codex Plugins view. Validate the bundled skill first: npx skills-ref validate plugins/hypawave/skills/hypawave (passes). (The bare skill also ships under .agents/skills/, covered by the agentskills.io line above.)
• ClawHub — clawhub skill publish dist/clawhub/hypawave. Do not validate this bundle with skills-ref — ClawHub is a separate format (top-level version, metadata.openclaw) that the agentskills.io validator intentionally rejects; ClawHub validates it at publish time.

Verification status

• Endpoints/fields cross-checked against llms.txt + openapi.json; nothing invented.
• Signing helper reproduces the published llms.txt test vector (run node core/scripts/sign_request.mjs --selftest).
• Frontmatter verified against each spec:
• agentskills.io: name ≤64 (lowercase/alnum/single-hyphen, matches dir), description ≤1024, license/compatibility/metadata optional; unknown fields tolerated; metadata values are strings.
• ClawHub: license is not a frontmatter field (registry-wide MIT-0; per-skill overrides unsupported) — omitted. The metadata.openclaw.install block was dropped — the signer's secp256k1 library is vendored, so nothing needs installing. version is semver.
• Hermes: folded into the standard variant (its platforms field is an OS enum — macos/linux/windows — not agent frameworks, and it accepts base agentskills.io skills).

Notes

• The buyer flow needs no key; seller and wave (signed) operations read HYPAWAVE_PRIVKEY or ~/.hypawave/identity.json (written once by --gen, shared with the MCP server), which never leaves the machine. The same key is the agent's identity for commerce and waves — back it up; a fresh key is a different agent. The bundled signer is self-contained (secp256k1 is vendored under scripts/vendor/) — it needs only Node 18+, no install.
• llms.txt and openapi.json at hypawave.com remain authoritative; the skill links to them rather than duplicating the manual.