@cloak.dev/claude-skills 0.2.1

package/bin/cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { cpSync, mkdirSync, readdirSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const skillsDir = join(__dirname, "..", "skills");
+const targetDir = join(homedir(), ".claude", "commands");
+
+mkdirSync(targetDir, { recursive: true });
+
+const files = readdirSync(skillsDir).filter((f) => f.endsWith(".md"));
+
+for (const file of files) {
+  cpSync(join(skillsDir, file), join(targetDir, file));
+  const name = file.replace(".md", "");
+  console.log(`  /${name}`);
+}
+
+console.log(`\nInstalled ${files.length} Cloak skills to ${targetDir}`);
+console.log("\nAvailable commands in Claude Code:");
+console.log("  /cloak-send    — One-shot private send (deposit + withdraw)");
+console.log("  /cloak-shield  — Deposit tokens into shielded pool");
+console.log("  /cloak-pay     — Spend from shielded balance");
+console.log("  /cloak-swap    — Private swap (SOL to USDC/USDT)");
+console.log("\nDocs: https://docs.cloak.ag");

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@cloak.dev/claude-skills",
+  "version": "0.2.1",
+  "type": "module",
+  "description": "Claude Code slash commands for private Solana transactions via Cloak — shield, pay, send, and swap",
+  "bin": {
+    "cloak-skills": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "skills"
+  ],
+  "keywords": [
+    "cloak",
+    "solana",
+    "privacy",
+    "claude-code",
+    "claude-skills",
+    "ai"
+  ],
+  "author": "Cloak Labs",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloak-ag/sdk.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/cloak-pay.md

@@ -0,0 +1,55 @@
+# Pay from Shielded Balance via Cloak
+
+You are helping the user spend from their shielded Cloak balance to pay a recipient.
+
+## Instructions
+
+1. Read https://docs.cloak.ag/llms.txt and https://docs.cloak.ag/sdk/llms.txt to understand the SDK.
+
+2. Parse the user's request to extract:
+   - **amount**: in human units (e.g. "5 USDC" = 5_000_000 base units). If "all" or no amount, use full withdraw.
+   - **recipient**: the destination wallet public key.
+   - **sender keypair path**: the user must specify the path to a `.json` keypair file.
+   - **UTXO file**: path to the `shielded-utxo.json` file created by `/cloak-shield`. Default to `shielded-utxo.json` in current directory.
+
+3. Create exactly one script file in the current directory:
+   - Name: `pay-from-shielded.ts`
+   - CLI: `npx tsx pay-from-shielded.ts <recipientPubkey> <amountBaseUnits> [utxoFile]`
+   - If amountBaseUnits equals the full UTXO amount, use `fullWithdraw()`. Otherwise use `partialWithdraw()`.
+   - Env: `SOLANA_RPC_URL` and `KEYPAIR_PATH` only
+   - Parse all args from `process.argv`
+   - Load the UTXO file, reconstruct the Utxo object using `deserializeUtxo()` or by rebuilding from saved fields (amount, keypair privateKey, mint, index)
+   - Use `partialWithdraw()` or `fullWithdraw()` with `externalAmount < 0` (withdraw)
+   - Keep `programId` as `CLOAK_PROGRAM_ID` internally
+   - Set `enforceViewingKeyRegistration: false`
+   - **For SPL token withdrawals (not native SOL)**: You MUST pre-build an Address Lookup Table (ALT) before calling `partialWithdraw`/`fullWithdraw`, because SPL transactions exceed Solana's 1232-byte legacy transaction limit. Use this pattern:
+     1. Import `getShieldPoolPDAs` from the SDK and `getAssociatedTokenAddressSync` from `@solana/spl-token`
+     2. Compute all known accounts: `SystemProgram.programId`, `SYSVAR_SLOT_HASHES_PUBKEY`, `SYSVAR_INSTRUCTIONS_PUBKEY`, `ComputeBudgetProgram.programId`, `programId`, pool PDAs (`pool`, `treasury`, `merkleTree`, `vaultAuthority`), pool vault ATA, payer ATA, `TOKEN_PROGRAM_ID`
+     3. Create and extend ALT using `AddressLookupTableProgram.createLookupTable()` and `extendLookupTable()` in one transaction
+     4. Wait for ALT activation: poll `getAddressLookupTable` up to 30 times with 500ms delay. Check activation with `result.value.isActive()` (method call, not property)
+     5. Pass the activated ALT as `addressLookupTableAccounts: [alt]` in `TransactOptions`
+     6. Retry ALT creation up to 3 times on "not a recent slot" errors (wait 2s between retries)
+   - If partial withdraw, save the change UTXO back to the UTXO file (overwrite with new change UTXO data)
+   - Print: `SENDER_WALLET=...`, `RECIPIENT_WALLET=...`, `AMOUNT_BASE_UNITS=...`, `WITHDRAW_SIGNATURE=...`
+   - If change UTXO exists, print: `REMAINING_SHIELDED=<amount> base units`
+   - Call `process.exit(0)` on success, `process.exit(1)` on failure
+
+4. Install dependencies if not already present: `npm install @cloak.dev/sdk @solana/web3.js tsx` (add `@solana/spl-token` for SPL tokens).
+
+5. Run the script with the extracted parameters. Use `SOLANA_RPC_URL=https://api.mainnet-beta.solana.com`.
+
+6. After success, verify:
+   - `solana confirm <WITHDRAW_SIGNATURE> --url https://api.mainnet-beta.solana.com`
+   - Check recipient token balance: `spl-token balance --owner <RECIPIENT> <MINT> --url https://api.mainnet-beta.solana.com` (or `solana balance` for SOL)
+
+7. Report the payment result clearly.
+
+## Token Mints
+
+- USDC: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` (6 decimals)
+- USDT: `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` (6 decimals)
+- SOL: native (9 decimals, use `NATIVE_SOL_MINT` from SDK)
+
+## User Request
+
+$ARGUMENTS

package/skills/cloak-send.md

@@ -0,0 +1,54 @@
+# Private Send via Cloak
+
+You are helping the user send tokens privately on Solana using the Cloak SDK (`@cloak.dev/sdk`).
+
+## Instructions
+
+1. Read the Cloak docs starting at https://docs.cloak.ag/llms.txt and https://docs.cloak.ag/ai-tools/ai-integration to understand the SDK contract.
+
+2. Parse the user's request to extract:
+   - **token**: SOL or SPL token (e.g. USDC). Default to SOL if not specified.
+   - **amount**: in human units (e.g. "5 USDC" = 5_000_000 base units for USDC with 6 decimals, "0.1 SOL" = 100_000_000 lamports).
+   - **recipient**: the destination wallet public key.
+   - **sender keypair path**: the user must specify the path to a `.json` keypair file in their prompt. If not provided, ask for it. Use this path as `KEYPAIR_PATH` env var.
+
+3. Create exactly one script file in the current directory following the Cloak docs minimal script contract:
+   - For SOL: `send-sol-private.ts`
+   - For SPL tokens: `send-private-<token>.ts` (e.g. `send-private-usdc.ts`)
+   - CLI: `npx tsx <script> <recipientPubkey> <amountBaseUnits>`
+   - Env: `SOLANA_RPC_URL` and `KEYPAIR_PATH` only
+   - Parse recipient/amount from `process.argv`
+   - Use `transact()` then `fullWithdraw()` UTXO flow
+   - Keep `programId` as `CLOAK_PROGRAM_ID` internally
+   - Set `enforceViewingKeyRegistration: false`
+   - **For SPL token sends (not native SOL)**: You MUST pre-build an Address Lookup Table (ALT) before calling `transact()` and `fullWithdraw()`, because SPL transactions exceed Solana's 1232-byte legacy transaction limit. Use this pattern:
+     1. Import `getShieldPoolPDAs` from the SDK and `getAssociatedTokenAddressSync` from `@solana/spl-token`
+     2. Compute all known accounts: `SystemProgram.programId`, `SYSVAR_SLOT_HASHES_PUBKEY`, `SYSVAR_INSTRUCTIONS_PUBKEY`, `ComputeBudgetProgram.programId`, `programId`, pool PDAs (`pool`, `treasury`, `merkleTree`, `vaultAuthority`), pool vault ATA, payer ATA, `TOKEN_PROGRAM_ID`
+     3. Create and extend ALT using `AddressLookupTableProgram.createLookupTable()` and `extendLookupTable()` in one transaction
+     4. Wait for ALT activation: poll `getAddressLookupTable` up to 30 times with 500ms delay. Check activation with `result.value.isActive()` (method call, not property)
+     5. Pass the activated ALT as `addressLookupTableAccounts: [alt]` in `TransactOptions` for both deposit and withdraw
+     6. Retry ALT creation up to 3 times on "not a recent slot" errors (wait 2s between retries)
+   - Print: `SENDER_WALLET=...`, `RECIPIENT_WALLET=...`, `AMOUNT_BASE_UNITS=...`
+   - Print: `DEPOSIT_SIGNATURE=...` and `WITHDRAW_SIGNATURE=...`
+   - Call `process.exit(0)` on success, `process.exit(1)` on failure
+
+4. Install dependencies: `npm install @cloak.dev/sdk @solana/web3.js tsx` (add `@solana/spl-token` for SPL tokens).
+
+5. Run the script with the extracted parameters. Use `SOLANA_RPC_URL=https://api.mainnet-beta.solana.com`.
+
+6. After the script completes successfully, run verification:
+   - `solana confirm <WITHDRAW_SIGNATURE> --url https://api.mainnet-beta.solana.com`
+   - For SOL: `solana balance <RECIPIENT> --url https://api.mainnet-beta.solana.com`
+   - For SPL: `spl-token balance --owner <RECIPIENT> <MINT> --url https://api.mainnet-beta.solana.com`
+
+7. Report the results clearly.
+
+## Token Mints
+
+- USDC: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` (6 decimals)
+- USDT: `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` (6 decimals)
+- SOL: native (9 decimals, use `NATIVE_SOL_MINT` from SDK)
+
+## User Request
+
+$ARGUMENTS

package/skills/cloak-shield.md

@@ -0,0 +1,53 @@
+# Shield Tokens via Cloak
+
+You are helping the user deposit tokens into Cloak's shielded pool using the Cloak SDK (`@cloak.dev/sdk`).
+
+## Instructions
+
+1. Read https://docs.cloak.ag/llms.txt and https://docs.cloak.ag/sdk/llms.txt to understand the SDK.
+
+2. Parse the user's request to extract:
+   - **token**: SOL or SPL token (e.g. USDC). Default to SOL if not specified.
+   - **amount**: in human units (e.g. "10 USDC" = 10_000_000 base units for 6-decimal USDC, "1 SOL" = 1_000_000_000 lamports).
+   - **sender keypair path**: the user must specify the path to a `.json` keypair file.
+
+3. Create exactly one script file in the current directory:
+   - Name: `shield-<token>.ts` (e.g. `shield-usdc.ts`, `shield-sol.ts`)
+   - CLI: `npx tsx shield-<token>.ts <amountBaseUnits>`
+   - Env: `SOLANA_RPC_URL` and `KEYPAIR_PATH` only
+   - Parse amount from `process.argv[2]`
+   - Use `transact()` with `externalAmount > 0` (deposit)
+   - **CRITICAL**: The padding/zero UTXO MUST use the same mint as the deposit. For SPL: `createZeroUtxo(USDC_MINT)`. For SOL: `createZeroUtxo()` or `createZeroUtxo(NATIVE_SOL_MINT)`. Mint mismatch causes proof generation failures.
+   - Keep `programId` as `CLOAK_PROGRAM_ID` internally
+   - Set `enforceViewingKeyRegistration: false`
+   - **For SPL token deposits (not native SOL)**: You MUST pre-build an Address Lookup Table (ALT) before calling `transact()`, because SPL deposits exceed Solana's 1232-byte legacy transaction limit. Use this pattern:
+     1. Import `getShieldPoolPDAs` from the SDK and `getAssociatedTokenAddressSync` from `@solana/spl-token`
+     2. Compute all known accounts: `SystemProgram.programId`, `SYSVAR_SLOT_HASHES_PUBKEY`, `SYSVAR_INSTRUCTIONS_PUBKEY`, `ComputeBudgetProgram.programId`, `programId`, pool PDAs (`pool`, `treasury`, `merkleTree`, `vaultAuthority`), pool vault ATA, payer ATA, `TOKEN_PROGRAM_ID`
+     3. Create and extend ALT using `AddressLookupTableProgram.createLookupTable()` and `extendLookupTable()` in one transaction
+     4. Wait for ALT activation: poll `getAddressLookupTable` up to 30 times with 500ms delay. Check activation with `result.value.isActive()` (method call, not property)
+     5. Pass the activated ALT as `addressLookupTableAccounts: [alt]` in `TransactOptions`
+     6. Retry ALT creation up to 3 times on "not a recent slot" errors (wait 2s between retries)
+   - After deposit, serialize the output UTXO using `serializeUtxo()` and save to `shielded-utxo.json` (JSON with hex-encoded bytes, amount, mint, index, and the UTXO keypair privateKey as hex for later spending)
+   - IMPORTANT: The saved file must contain everything needed to spend later: `{ utxoBytes: string, amount: string, mint: string, index: number, keypairPrivateKey: string }`
+   - Print: `WALLET=...`, `AMOUNT_BASE_UNITS=...`, `DEPOSIT_SIGNATURE=...`, `UTXO_FILE=shielded-utxo.json`
+   - Call `process.exit(0)` on success, `process.exit(1)` on failure
+
+4. Install dependencies: `npm install @cloak.dev/sdk @solana/web3.js tsx` (add `@solana/spl-token` for SPL tokens).
+
+5. Run the script with the extracted parameters. Use `SOLANA_RPC_URL=https://api.mainnet-beta.solana.com`.
+
+6. After success, verify:
+   - Confirm the deposit tx: `solana confirm <DEPOSIT_SIGNATURE> --url https://api.mainnet-beta.solana.com`
+   - Show the saved UTXO file exists and its contents (redact keypairPrivateKey in output)
+
+7. Report: "Your shielded balance is ready. Use `/cloak-pay` to spend from it."
+
+## Token Mints
+
+- USDC: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` (6 decimals)
+- USDT: `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` (6 decimals)
+- SOL: native (9 decimals, use `NATIVE_SOL_MINT` from SDK)
+
+## User Request
+
+$ARGUMENTS

package/skills/cloak-swap.md

@@ -0,0 +1,59 @@
+# Private Swap via Cloak
+
+You are helping the user privately swap SOL into an SPL token using the Cloak SDK (`@cloak.dev/sdk`).
+
+## Instructions
+
+1. Read https://docs.cloak.ag/llms.txt and https://docs.cloak.ag/sdk/llms.txt to understand the SDK. Pay special attention to section 6.6 (Swap SOL -> SPL).
+
+2. Parse the user's request to extract:
+   - **input amount**: SOL amount in human units (e.g. "0.05 SOL" = 50_000_000 lamports).
+   - **output token**: SPL token to receive (e.g. USDC, USDT). Default to USDC if not specified.
+   - **recipient**: wallet to receive the output tokens. If not specified, use the sender's own wallet.
+   - **sender keypair path**: the user must specify the path to a `.json` keypair file.
+   - **slippage**: in basis points. Default to 1500 (15%) for small amounts, 500 (5%) for larger amounts.
+
+3. Create exactly one script file in the current directory:
+   - Name: `swap-sol-to-<token>.ts` (e.g. `swap-sol-to-usdc.ts`)
+   - CLI: `npx tsx swap-sol-to-<token>.ts <recipientPubkey> <solLamports> [slippageBps]`
+   - Env: `SOLANA_RPC_URL` and `KEYPAIR_PATH` only
+   - Parse all args from `process.argv`
+   - Flow:
+     1. Deposit SOL into shielded pool via `transact()` with `externalAmount > 0`
+     2. Get Jupiter quote via `@jup-ag/api` (`createJupiterApiClient().quoteGet(...)`)
+     3. Call `swapWithChange()` with the shielded UTXOs, swap amount, output mint, recipient ATA, and minOutputAmount from Jupiter quote
+   - Use `getAssociatedTokenAddress` from `@solana/spl-token` for recipient ATA
+   - Keep `programId` as `CLOAK_PROGRAM_ID` internally
+   - Set `enforceViewingKeyRegistration: false`
+   - Pass `swapSlippageBps`, `swapStatusMaxAttempts: 60`, `swapStatusDelayMs: 2000` in options
+   - Pass `recipientWallet` (the recipient's PublicKey) so relay can create ATA if missing
+   - Use `cachedMerkleTree` from deposit result for the swap call
+   - Print: `SENDER_WALLET=...`, `RECIPIENT_WALLET=...`, `INPUT_AMOUNT_LAMPORTS=...`, `OUTPUT_TOKEN=...`
+   - Print: `DEPOSIT_SIGNATURE=...`, `SWAP_SIGNATURE=...`, `SWAP_STATE_PDA=...`
+   - Call `process.exit(0)` on success, `process.exit(1)` on failure
+
+4. Install dependencies: `npm install @cloak.dev/sdk @solana/web3.js @solana/spl-token @jup-ag/api tsx`
+
+5. Run the script with the extracted parameters. Use `SOLANA_RPC_URL=https://api.mainnet-beta.solana.com`.
+
+6. After success, verify:
+   - Check recipient token balance BEFORE running the script (or record it in the script before the swap)
+   - `solana confirm <SWAP_SIGNATURE> --url https://api.mainnet-beta.solana.com`
+   - Check recipient token balance AFTER: `spl-token balance --owner <RECIPIENT> <OUTPUT_MINT> --url https://api.mainnet-beta.solana.com`
+   - Calculate actual received = balance_after - balance_before
+   - Report the actual amount received (not the Jupiter quote estimate)
+
+7. Report the results clearly:
+   - Actual tokens received (balance diff, not quote)
+   - Effective rate = actual_received / input_SOL
+   - Note that Cloak charges a protocol fee (0.005 SOL fixed + 0.3% variable) on the withdrawal side of the swap
+
+## Token Mints
+
+- USDC: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` (6 decimals)
+- USDT: `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` (6 decimals)
+- SOL: native (9 decimals, use `NATIVE_SOL_MINT` from SDK, mint address `So11111111111111111111111111111111111111112`)
+
+## User Request
+
+$ARGUMENTS