shadowskill

shadow skill

shadow skill is a privacy-preserving cross-chain crypto transfer and swap Agent Skill suite. The primary Agent entrypoint is shadow-skill, a provider-neutral router that can choose among Web3 products based on the user's chain, asset, amount, privacy, cost, speed, and execution requirements.

The first bundled provider adapter is powered by the official HoudiniSwap Partner API v2. HoudiniSwap is a provider inside the framework, not the user-facing name of the skill.

This project lets AI agents (Claude Code, OpenClaw, Hermes, Pi, Cursor, Codex, Gemini CLI, and any other tool that supports the open SKILL.md specification) understand and execute privacy-preserving cross-chain intents: plan routes, compare provider quotes, create orders, poll for completion, and submit provider-specific batches in natural language.

Highlights

• Primary Agent entrypoint. skills/shadow-skill/SKILL.md is the recommended skill for agents to discover and use for private transfer/swap intents.
• Provider-neutral routing. shadow skill chooses a provider by privacy requirement first, then output amount, then speed. HoudiniSwap remains available as the first bundled adapter.
• Compatibility preserved. skills/privacy-router/ remains as a routing compatibility alias, and skills/houdiniswap/ remains as a direct HoudiniSwap provider skill.
• Zero runtime dependencies. Helper scripts use only Node.js v22+ built-ins (fetch, URL, AbortController, node:util parseArgs). No npm install required at runtime.
• Tested. 65 offline tests + 2 opt-in live tests, run on a CI matrix of Node 22/24 x Ubuntu/macOS/Windows.
• Privacy-first by design. Strict privacy requirements are never silently downgraded; if no provider can satisfy a route, the router returns an unmet result instead of creating an order.

Prerequisites

• Node.js v22 LTS or newer. Verify with node --version.
• A HoudiniSwap account is optional for the bundled provider: read-only flows (token search, quotes) work with the public partner-id; creating exchanges requires a partner API key.

If you do not have Node v22 yet, the recommended installers are:

Platform	Command
macOS / Linux	nvm install 22 && nvm use 22 (or fnm use)
Windows	winget install OpenJS.NodeJS.LTS (or fnm use)
Direct download	https://nodejs.org/

The repo's .nvmrc pins 22, so nvm use / fnm use will switch automatically when you cd into it.

Quick install

macOS / Linux

git clone https://github.com/REPLACE_ME/shadow-skill.git
cd shadow-skill
bash scripts/install.sh

Windows (PowerShell)

git clone https://github.com/REPLACE_ME/shadow-skill.git
cd shadow-skill
powershell -ExecutionPolicy Bypass -File scripts/install.ps1

The installer:

1. Verifies node --version is >= 22 (refuses to continue otherwise, with platform-specific guidance; it never installs Node for you).
2. Installs dependencies with npm ci (currently zero packages, but the hook is there for future extensions).
3. Copies .env.example to .env (preserves an existing .env) and tightens its local file permissions.
4. Runs the offline smoke test suite (npm run smoke).
5. Symlinks skills/shadow-skill/, skills/privacy-router/, and skills/houdiniswap/ into every agent's standard skills directory that exists on this machine (~/.claude/skills/, ~/.openclaw/skills/, ~/.hermes/skills/, ~/.pi/agent/skills/, ~/.cursor/skills/), then verifies the deployment is readable end-to-end via scripts/verify-deployment.sh.

Pass --no-link if you only want steps 1-4 (CI, container builds, etc.), or --copy to fall back from symlinks to plain copies.

shadow skill routing

Use shadow skill when the user wants the agent to decide which Web3 product or blockchain route should satisfy a private transfer/swap:

node scripts/router/list-providers.mjs
node scripts/router/plan-transfer.mjs \
  --from-chain solana --to-chain ethereum \
  --from-asset SOL --to-asset ETH --amount 1.5 \
  --privacy unlinkability
node scripts/router/get-quotes.mjs \
  --from-chain solana --to-chain ethereum \
  --from-asset SOL --to-asset ETH --amount 1.5 \
  --privacy unlinkability

When called from an installed Agent skill directory, use the shadow-skill wrappers instead:

cd ~/.claude/skills/shadow-skill
node scripts/list-providers.mjs
node scripts/get-quotes.mjs \
  --from-chain solana --to-chain ethereum \
  --from-asset SOL --to-asset ETH --amount 1.5 \
  --privacy unlinkability

get-quotes returns all eligible quotes plus selectedQuote. Routed quote and order IDs are formatted as <provider>:<providerObjectId>, for example houdiniswap:q-..., so follow-up commands can dispatch to the right adapter:

node scripts/router/create-order.mjs \
  --quote-id houdiniswap:<quoteId> \
  --address-to 0xRecipient...
node scripts/router/wait-order.mjs --id houdiniswap:<orderId>

The router currently bundles one provider adapter, HoudiniSwap. Future providers can be added by registering another adapter with the same capability, quote, and order interfaces.

Configure auth

Open .env and set one of these HoudiniSwap provider auth modes:

# Mode A: full API key (read + write)
HOUDINISWAP_API_KEY=
HOUDINISWAP_API_SECRET=

# Mode B: public partner-id (read-only)
HOUDINISWAP_PARTNER_ID_PUBLIC=

create-exchange, get-order, wait-for-order, and multi-swap require Mode A. search-tokens, list-chains, and get-quote work in either mode. Full details are in skills/houdiniswap/references/auth.md.

If you point HOUDINISWAP_BASE_URL at a mock or staging endpoint, also set HOUDINISWAP_ALLOW_CUSTOM_BASE_URL=1. Authenticated requests are otherwise restricted to the official https://api-partner.houdiniswap.com origin so the client does not leak credentials to arbitrary hosts.

If you configure a private chain RPC override like ETHEREUM_RPC_URL, public fallback is disabled by default. Set <CHAIN_SHORTNAME_UPPER>_RPC_URL_ALLOW_FALLBACK=1 only if you explicitly want the verifier to roll over to public RPC providers when your private endpoint is down.

Install the skills into your agent

Why this matters. Every SKILL.md-compatible agent (Claude Code, OpenClaw, Hermes, Pi, Cursor, etc.) expects a directory layout where SKILL.md is at the top level of <agent-skills-dir>/<skill-name>/. This repo is a multi-skill monorepo with SKILL.md files nested under skills/. The installer reconciles the two structures by symlinking the inner skill directories into the agent's expected location.

graph LR
  subgraph repo["Cloned repo (dev view)"]
    A[".env"]
    B["package.json"]
    C["scripts/install.sh"]
    D["skills/shadow-skill/<br/>SKILL.md<br/>scripts/"]
    E["skills/privacy-router/<br/>SKILL.md<br/>scripts/<br/>lib/"]
    F["skills/houdiniswap/<br/>SKILL.md<br/>scripts/<br/>references/<br/>tests/"]
  end
  subgraph agent["~/.claude/skills/ (agent view)"]
    G["shadow-skill/<br/>SKILL.md<br/>scripts/"]
    H["privacy-router/<br/>SKILL.md<br/>scripts/<br/>lib/"]
    I["houdiniswap/<br/>SKILL.md<br/>scripts/<br/>references/<br/>tests/"]
  end
  D -. "ln -s" .-> G
  E -. "ln -s" .-> H
  F -. "ln -s" .-> I
  A -. "auto-loaded by<br/>_client.mjs<br/>via parent search" .-> I

scripts/install.sh does the symlink for you and verifies it works end-to-end. The HoudiniSwap provider client auto-loads .env from any of: the symlink target itself, any of its ancestor directories (which includes the cloned-repo root), or ~/.claude/skills/houdiniswap/.env. You only need one .env and you only need to edit it in one place: the cloned repo root.

One command (recommended)

After bash scripts/install.sh (or install.ps1) finishes, shadow-skill is already linked into every agent skills dir that exists on your machine and has been verified to be loadable.

If you only want to redo the linking step (for example, you changed which agents are installed):

bash scripts/install.sh --link-only
# or, if your filesystem doesn't support symlinks:
bash scripts/install.sh --link-only --copy

To verify a deployment without re-linking:

bash scripts/verify-deployment.sh

Manual install

The recommended skill source dir is skills/shadow-skill/. Install all three source dirs as siblings: shadow-skill wraps privacy-router, and privacy-router loads the bundled houdiniswap provider via relative imports. The sibling dirs also provide the backward-compatible routing alias and direct HoudiniSwap provider commands.

Agent	Recommended global path	Project-scoped path
Claude Code	~/.claude/skills/shadow-skill	<project>/.claude/skills/shadow-skill
OpenClaw	~/.openclaw/skills/shadow-skill	<workspace>/skills/shadow-skill
Hermes (Nous)	~/.hermes/skills/shadow-skill (POSIX/WSL2); %LOCALAPPDATA%\hermes\skills\shadow-skill (native Windows)	<workspace>/.hermes/skills/shadow-skill
Pi	~/.pi/agent/skills/shadow-skill	<workspace>/.pi/skills/shadow-skill
Cursor	~/.cursor/skills/shadow-skill	<workspace>/.cursor/skills/shadow-skill
Codex / others	check that tool's docs	-

# macOS / Linux
mkdir -p ~/.claude/skills
ln -snf "$(pwd)/skills/shadow-skill" ~/.claude/skills/shadow-skill
ln -snf "$(pwd)/skills/privacy-router" ~/.claude/skills/privacy-router
ln -snf "$(pwd)/skills/houdiniswap" ~/.claude/skills/houdiniswap

# Windows (junction works without admin / dev mode)
New-Item -ItemType Directory -Force $env:USERPROFILE\.claude\skills | Out-Null
New-Item -ItemType Junction `
  -Path "$env:USERPROFILE\.claude\skills\shadow-skill" `
  -Target "$(Get-Location)\skills\shadow-skill"
New-Item -ItemType Junction `
  -Path "$env:USERPROFILE\.claude\skills\privacy-router" `
  -Target "$(Get-Location)\skills\privacy-router"
New-Item -ItemType Junction `
  -Path "$env:USERPROFILE\.claude\skills\houdiniswap" `
  -Target "$(Get-Location)\skills\houdiniswap"

Restart your agent so it re-scans the skills directory. The skill is auto-discovered via the name + description in its frontmatter.

What if I just cp -R the whole repo?

Agents look for <skills-dir>/<skill-name>/SKILL.md, so dropping the entire repo at ~/.claude/skills/shadow-skill/ produces shadow-skill/skills/shadow-skill/SKILL.md, one level too deep. Use install.sh instead, which links the inner skill directories into the right places. The accompanying scripts/tests/.env all stay in the cloned repo and the auto-loader walks up to find them.

If you must use cp because the destination filesystem does not support symlinks, use:

bash scripts/install.sh --copy

It will cp -R skills/shadow-skill/, skills/privacy-router/, and skills/houdiniswap/ into each agent dir under the correct names, and it will warn you that the deployed copy is now detached from the repo.

What shadow skill can do

Capability	Recommended command
List available privacy providers	scripts/router/list-providers.mjs
Plan a private transfer/swap route	scripts/router/plan-transfer.mjs
Compare provider quotes	scripts/router/get-quotes.mjs
Create a routed order	scripts/router/create-order.mjs
Fetch routed order status	scripts/router/get-order.mjs
Poll routed order status	scripts/router/wait-order.mjs

The direct HoudiniSwap provider skill also exposes provider-specific helper CLIs for token search, chain listing, address verification, tx verification, and batch order submission. Its SKILL.md tells an agent when to use those lower-level tools.

Architecture

This repository is structured as an installable Agent Skill package, not a long-running service. The main runtime is a thin CLI layer over a provider-neutral routing model. The first provider adapter wraps the HoudiniSwap API client, with a separate chain-verification adapter layer for EVM, Solana, UTXO, Tron, and explorer-only fallbacks.

See skills/houdiniswap/references/architecture.md for the detailed provider architecture, Mermaid diagrams, and swap-flow sequence.

Testing

npm test                        # 65 offline tests, ~2s
npm run smoke                   # _client + list-chains + router smoke tests
npm run test:coverage           # with built-in coverage reporter
HOUDINISWAP_LIVE=1 npm test     # also run 2 opt-in live read-only tests

CI runs the offline suite on Node 22 and 24 across Ubuntu, macOS, and Windows. See skills/houdiniswap/references/testing.md for layout, mock server design, and how to add tests for new scripts.

Verifying connectivity to the real API

If you want to confirm your HoudiniSwap provider credentials and network actually reach the real API without spending funds, run the opt-in live suite:

HOUDINISWAP_LIVE=1 npm test

It only hits read-only endpoints (/v2/chains, /v2/tokens?term=USDC).

Repository layout

shadow-skill/
├── README.md                 # this file
├── LICENSE                   # MIT
├── package.json              # ESM manifest, engines.node>=22
├── .nvmrc                    # 22
├── .env.example              # auth env-var template
├── scripts/
│   ├── install.sh            # POSIX one-line installer
│   ├── install.ps1           # Windows installer
│   ├── verify-deployment.sh  # skill deployment verifier
│   ├── router/               # repo-root wrappers for routed commands
│   └── run-tests.mjs         # cross-platform test runner
└── skills/
    ├── shadow-skill/         # recommended Agent skill entrypoint
    ├── privacy-router/       # compatibility routing entrypoint
    └── houdiniswap/          # bundled HoudiniSwap provider adapter

SafuSkill submission checklist

This repo is built to satisfy SafuSkill.ai's indexing criteria out of the box:

• Public GitHub repository (you publish the repo).
• README.md explaining what the skill does and how to use it.
• LICENSE - MIT.
• package.json manifest with name, description, keywords, license, repository, engines.node>=22.
• No hardcoded secrets; all credentials come from .env.
• CI badge + green test suite (quality signal).
• Add the recommended GitHub topics to your repo settings: agent-skill, ai-agent-tool, claude-code, openclaw, hermes-agent, pi-agent, pi-coding-agent, cursor, mcp-server, skill-md, shadow-skill, crypto, defi, privacy, cross-chain.
• Reach >= 5 GitHub stars for auto-discovery.

Acknowledgements

• HoudiniSwap - first bundled provider adapter, Partner API v2, and product docs.
• Anthropic AgentSkills spec
  • open SKILL.md standard.

License

MIT - see LICENSE.