diff --git a/bankr-agent-dev/skills/bankr-client-patterns/SKILL.md b/bankr-agent-dev/skills/bankr-client-patterns/SKILL.md
index 4e466c9..8fe2061 100644
--- a/bankr-agent-dev/skills/bankr-client-patterns/SKILL.md
+++ b/bankr-agent-dev/skills/bankr-client-patterns/SKILL.md
@@ -1,16 +1,20 @@
 ---
-name: Bankr Dev - Client Patterns
-description: This skill should be used when the user asks to "implement Bankr client", "write bankr-client.ts", "create API client for Bankr", "common files for Bankr project", "package.json for Bankr", "tsconfig for Bankr", "Bankr TypeScript patterns", "Bankr response types", or needs the reusable client code and common project files for Bankr API integrations.
-version: 1.0.0
+name: bankr-client-patterns
+description: "Use when building a Bankr API client in TypeScript, setting up project scaffolding (package.json, tsconfig.json, .env), or implementing reusable patterns for job submission, status polling, cancellation, and error handling with the Bankr REST API at api.bankr.bot."
 ---
 
 # Bankr Client Patterns
 
-Reusable client code and common files for Bankr API projects.
+Reusable TypeScript client code and project scaffolding for Bankr API integrations.
 
-## bankr-client.ts
+## Workflow
 
-The core API client module for all Bankr projects:
+1. Create project files (package.json, tsconfig.json, .env) from templates below
+2. Add `bankr-client.ts` as the core API module
+3. Use `execute()` for simple prompt-and-wait, or `submitPrompt()` + `waitForCompletion()` for manual control
+4. Handle terminal job states: `completed`, `failed`, `cancelled`
+
+## bankr-client.ts — Core Types
 
 ```typescript
 import "dotenv/config";
@@ -18,10 +22,6 @@ import "dotenv/config";
 const API_URL = process.env.BANKR_API_URL || "https://api.bankr.bot";
 const API_KEY = process.env.BANKR_API_KEY;
 
-// ============================================
-// Types
-// ============================================
-
 export type JobStatus = "pending" | "processing" | "completed" | "failed" | "cancelled";
 
 export interface JobStatusResponse {
@@ -32,477 +32,157 @@ export interface JobStatusResponse {
   response?: string;
   transactions?: Transaction[];
   richData?: RichData[];
-  statusUpdates?: StatusUpdate[];
+  statusUpdates?: { message: string; timestamp: string }[];
   error?: string;
   createdAt: string;
   startedAt?: string;
   completedAt?: string;
-  cancelledAt?: string;
   processingTime?: number;
   cancellable?: boolean;
 }
 
-export interface StatusUpdate {
-  message: string;
-  timestamp: string;
-}
-
-// Transaction types
+// Transaction union — each variant has a `type` discriminator and `metadata`
 export type Transaction =
-  | SwapTransaction
-  | ApprovalTransaction
-  | TransferErc20Transaction
-  | TransferEthTransaction
-  | ConvertEthToWethTransaction
-  | ConvertWethToEthTransaction
-  | TransferNftTransaction
-  | MintManifoldNftTransaction
-  | MintSeaDropNftTransaction
-  | BuyNftTransaction
-  | AvantisTradeTransaction
-  | SwapCrossChainTransaction
-  | ManageBankrStakingTransaction;
+  | { type: "swap"; metadata: BaseTransactionMetadata & { approvalRequired?: boolean; approvalTx?: { to: string; data: string }; permit2?: object } }
+  | { type: "approval" | "transfer_erc20" | "transfer_eth" | "convert_eth_to_weth" | "convert_weth_to_eth" | "transfer_nft" | "mint_manifold_nft" | "mint_seadrop_nft" | "buy_nft"; metadata: BaseTransactionMetadata }
+  | { type: "avantisTrade" | "swapCrossChain" | "manage_bankr_staking"; metadata: { chainId: number; description: string; to: string; data: string; value?: string } };
 
 interface BaseTransactionMetadata {
   __ORIGINAL_TX_DATA__: {
-    chain: string;
-    humanReadableMessage: string;
-    inputTokenAddress: string;
-    inputTokenAmount: string;
-    inputTokenTicker: string;
-    outputTokenAddress: string;
-    outputTokenTicker: string;
-    receiver: string;
-  };
-  transaction: {
-    chainId: number;
-    to: string;
-    data: string;
-    gas: string;
-    gasPrice: string;
-    value: string;
-  };
-}
-
-export interface SwapTransaction {
-  type: "swap";
-  metadata: BaseTransactionMetadata & {
-    approvalRequired?: boolean;
-    approvalTx?: { to: string; data: string };
-    permit2?: object;
-  };
-}
-
-export interface ApprovalTransaction {
-  type: "approval";
-  metadata: BaseTransactionMetadata;
-}
-
-export interface TransferErc20Transaction {
-  type: "transfer_erc20";
-  metadata: BaseTransactionMetadata;
-}
-
-export interface TransferEthTransaction {
-  type: "transfer_eth";
-  metadata: BaseTransactionMetadata;
-}
-
-export interface ConvertEthToWethTransaction {
-  type: "convert_eth_to_weth";
-  metadata: BaseTransactionMetadata;
-}
-
-export interface ConvertWethToEthTransaction {
-  type: "convert_weth_to_eth";
-  metadata: BaseTransactionMetadata;
-}
-
-export interface TransferNftTransaction {
-  type: "transfer_nft";
-  metadata: BaseTransactionMetadata;
-}
-
-export interface MintManifoldNftTransaction {
-  type: "mint_manifold_nft";
-  metadata: BaseTransactionMetadata;
-}
-
-export interface MintSeaDropNftTransaction {
-  type: "mint_seadrop_nft";
-  metadata: BaseTransactionMetadata;
-}
-
-export interface BuyNftTransaction {
-  type: "buy_nft";
-  metadata: BaseTransactionMetadata;
-}
-
-export interface AvantisTradeTransaction {
-  type: "avantisTrade";
-  metadata: {
-    chainId: number;
-    description: string;
-    to: string;
-    data: string;
-    value?: string;
-  };
-}
-
-export interface SwapCrossChainTransaction {
-  type: "swapCrossChain";
-  metadata: {
-    chainId: number;
-    description: string;
-    to: string;
-    data: string;
-    value: string;
-  };
-}
-
-export interface ManageBankrStakingTransaction {
-  type: "manage_bankr_staking";
-  metadata: {
-    chainId: number;
-    description: string;
-    to: string;
-    data: string;
-    value?: string;
+    chain: string; humanReadableMessage: string;
+    inputTokenAddress: string; inputTokenAmount: string; inputTokenTicker: string;
+    outputTokenAddress: string; outputTokenTicker: string; receiver: string;
   };
+  transaction: { chainId: number; to: string; data: string; gas: string; gasPrice: string; value: string };
 }
 
-// Rich data types
-export type RichData = SocialCard | Chart;
-
-export interface SocialCard {
-  type: "social-card";
-  variant: "analysis";
-  text: string;
-}
-
-export interface Chart {
-  type: "chart";
-  url: string;
-}
+export type RichData = { type: "social-card"; variant: "analysis"; text: string } | { type: "chart"; url: string };
+```
 
-// ============================================
-// API Functions
-// ============================================
+## bankr-client.ts — API Functions
 
+```typescript
 export async function submitPrompt(prompt: string): Promise<{ jobId: string }> {
-  if (!API_KEY) {
-    throw new Error("BANKR_API_KEY not set. Get one at https://bankr.bot/api");
-  }
-
-  const response = await fetch(`${API_URL}/agent/prompt`, {
+  if (!API_KEY) throw new Error("BANKR_API_KEY not set. Get one at https://bankr.bot/api");
+  const res = await fetch(`${API_URL}/agent/prompt`, {
     method: "POST",
-    headers: {
-      "x-api-key": API_KEY,
-      "Content-Type": "application/json",
-    },
+    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
     body: JSON.stringify({ prompt }),
   });
-
-  if (!response.ok) {
-    const text = await response.text();
-    throw new Error(`API error ${response.status}: ${text}`);
-  }
-
-  const data = await response.json();
-  if (!data.success) {
-    throw new Error(data.error || "Failed to submit prompt");
-  }
-
+  if (!res.ok) throw new Error(`API error ${res.status}: ${await res.text()}`);
+  const data = await res.json();
+  if (!data.success) throw new Error(data.error || "Failed to submit prompt");
   return { jobId: data.jobId };
 }
 
 export async function getJobStatus(jobId: string): Promise<JobStatusResponse> {
-  if (!API_KEY) {
-    throw new Error("BANKR_API_KEY not set");
-  }
-
-  const response = await fetch(`${API_URL}/agent/job/${jobId}`, {
-    headers: { "x-api-key": API_KEY },
-  });
-
-  if (!response.ok) {
-    const text = await response.text();
-    throw new Error(`API error ${response.status}: ${text}`);
-  }
-
-  return response.json();
+  if (!API_KEY) throw new Error("BANKR_API_KEY not set");
+  const res = await fetch(`${API_URL}/agent/job/${jobId}`, { headers: { "x-api-key": API_KEY } });
+  if (!res.ok) throw new Error(`API error ${res.status}: ${await res.text()}`);
+  return res.json();
 }
 
 export async function cancelJob(jobId: string): Promise<JobStatusResponse> {
-  if (!API_KEY) {
-    throw new Error("BANKR_API_KEY not set");
-  }
-
-  const response = await fetch(`${API_URL}/agent/job/${jobId}/cancel`, {
-    method: "POST",
-    headers: {
-      "x-api-key": API_KEY,
-      "Content-Type": "application/json",
-    },
+  if (!API_KEY) throw new Error("BANKR_API_KEY not set");
+  const res = await fetch(`${API_URL}/agent/job/${jobId}/cancel`, {
+    method: "POST", headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
   });
-
-  if (!response.ok) {
-    const text = await response.text();
-    throw new Error(`API error ${response.status}: ${text}`);
-  }
-
-  return response.json();
+  if (!res.ok) throw new Error(`API error ${res.status}: ${await res.text()}`);
+  return res.json();
 }
 
 export async function waitForCompletion(
-  jobId: string,
-  onProgress?: (message: string) => void,
-  options?: { pollInterval?: number; maxAttempts?: number }
+  jobId: string, onProgress?: (msg: string) => void,
+  opts?: { pollInterval?: number; maxAttempts?: number }
 ): Promise<JobStatusResponse> {
-  const pollInterval = options?.pollInterval || 2000;
-  const maxAttempts = options?.maxAttempts || 150; // 5 minutes max
-  let lastUpdateCount = 0;
-
-  for (let attempt = 0; attempt < maxAttempts; attempt++) {
-    const status = await getJobStatus(jobId);
-
-    // Report new status updates
-    if (onProgress && status.statusUpdates) {
-      for (let i = lastUpdateCount; i < status.statusUpdates.length; i++) {
-        onProgress(status.statusUpdates[i].message);
-      }
-      lastUpdateCount = status.statusUpdates.length;
-    }
-
-    // Check for terminal states
-    if (["completed", "failed", "cancelled"].includes(status.status)) {
-      return status;
-    }
-
-    await new Promise((resolve) => setTimeout(resolve, pollInterval));
+  const interval = opts?.pollInterval || 2000;
+  const max = opts?.maxAttempts || 150;
+  let seen = 0;
+  for (let i = 0; i < max; i++) {
+    const s = await getJobStatus(jobId);
+    if (onProgress && s.statusUpdates)
+      for (let j = seen; j < s.statusUpdates.length; j++) onProgress(s.statusUpdates[j].message);
+    seen = s.statusUpdates?.length || 0;
+    if (["completed", "failed", "cancelled"].includes(s.status)) return s;
+    await new Promise(r => setTimeout(r, interval));
   }
-
-  throw new Error("Job timed out after maximum attempts");
+  throw new Error("Job timed out");
 }
 
-/**
- * Execute a Bankr prompt and wait for completion
- * Convenience function that combines submit + poll
- */
-export async function execute(
-  prompt: string,
-  onProgress?: (message: string) => void
-): Promise<JobStatusResponse> {
+/** Submit prompt and wait — convenience wrapper */
+export async function execute(prompt: string, onProgress?: (msg: string) => void): Promise<JobStatusResponse> {
   const { jobId } = await submitPrompt(prompt);
   onProgress?.(`Job submitted: ${jobId}`);
   return waitForCompletion(jobId, onProgress);
 }
 ```
 
----
-
-## Common Files
+## Project Scaffolding
 
 ### package.json
 
-Base package.json for all Bankr projects:
-
 ```json
 {
   "name": "{project-name}",
   "version": "0.1.0",
-  "description": "{description}",
   "type": "module",
   "main": "dist/index.js",
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts"
-  },
-  "dependencies": {
-    "dotenv": "^16.3.1"
-  },
-  "devDependencies": {
-    "@types/node": "^20.10.0",
-    "tsx": "^4.7.0",
-    "typescript": "^5.3.0"
-  }
-}
-```
-
-#### Framework-Specific Dependencies
-
-Add based on project template:
-
-**Web Service (Express):**
-```json
-"dependencies": {
-  "express": "^4.18.0"
-},
-"devDependencies": {
-  "@types/express": "^4.17.21"
+  "scripts": { "build": "tsc", "start": "node dist/index.js", "dev": "tsx src/index.ts" },
+  "dependencies": { "dotenv": "^16.3.1" },
+  "devDependencies": { "@types/node": "^20.10.0", "tsx": "^4.7.0", "typescript": "^5.3.0" }
 }
 ```
 
-**Web Service (Fastify):**
-```json
-"dependencies": {
-  "fastify": "^4.25.0"
-}
-```
-
-**CLI:**
-```json
-"dependencies": {
-  "commander": "^12.0.0"
-}
-```
-
----
+Add framework deps as needed: `express@^4.18` + `@types/express`, `fastify@^4.25`, or `commander@^12.0`.
 
 ### tsconfig.json
 
-TypeScript configuration:
-
 ```json
 {
   "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "declaration": true
+    "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext",
+    "outDir": "./dist", "rootDir": "./src", "strict": true,
+    "esModuleInterop": true, "skipLibCheck": true, "declaration": true
   },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
+  "include": ["src/**/*"], "exclude": ["node_modules", "dist"]
 }
 ```
 
----
-
 ### .env.example
 
-Environment variables template:
-
 ```bash
-# Bankr API Configuration
 BANKR_API_KEY=bk_your_api_key_here
 BANKR_API_URL=https://api.bankr.bot
-
-# Optional: Wallet address for context
 BANKR_WALLET_ADDRESS=0x...
 ```
 
----
-
-### .gitignore
-
-Standard ignore patterns:
-
-```
-# Dependencies
-node_modules/
-
-# Build output
-dist/
-
-# Environment
-.env
-.env.local
-.env.*.local
-
-# Logs
-*.log
-npm-debug.log*
-
-# IDE
-.idea/
-.vscode/
-*.swp
-*.swo
-
-# OS
-.DS_Store
-Thumbs.db
-
-# Testing
-coverage/
-```
-
----
-
-## Usage Patterns
-
-### Basic Usage
+## Usage Examples
 
 ```typescript
+// Basic — prompt and wait
 import { execute } from "./bankr-client";
-
-const result = await execute("What is the price of ETH?", (msg) => {
-  console.log("Progress:", msg);
-});
-
+const result = await execute("What is the price of ETH?", console.log);
 console.log(result.response);
-```
-
-### With Error Handling
-
-```typescript
-import { execute } from "./bankr-client";
 
+// With error handling
 try {
   const result = await execute("Buy $50 of ETH on Base");
-
   if (result.status === "completed") {
-    console.log("Success:", result.response);
-
-    // Handle transactions
-    if (result.transactions) {
-      for (const tx of result.transactions) {
-        console.log(`${tx.type}:`, tx.metadata.__ORIGINAL_TX_DATA__?.humanReadableMessage);
-      }
-    }
-  } else if (result.status === "failed") {
-    console.error("Failed:", result.error);
-  }
-} catch (error) {
-  console.error("Error:", error.message);
-}
-```
-
-### Manual Control
-
-```typescript
+    console.log(result.response);
+    result.transactions?.forEach(tx =>
+      console.log(`${tx.type}: ${tx.metadata.__ORIGINAL_TX_DATA__?.humanReadableMessage}`)
+    );
+  } else console.error("Failed:", result.error);
+} catch (e) { console.error(e.message); }
+
+// Manual control — submit, poll, cancel
 import { submitPrompt, waitForCompletion, cancelJob } from "./bankr-client";
-
-// Submit
 const { jobId } = await submitPrompt("Analyze ETH market");
-
-// Set up timeout
-const timeout = setTimeout(() => {
-  cancelJob(jobId);
-}, 120000);
-
-// Wait with custom options
-const result = await waitForCompletion(jobId, console.log, {
-  pollInterval: 2000,
-  maxAttempts: 60,
-});
-
+const timeout = setTimeout(() => cancelJob(jobId), 120000);
+const result = await waitForCompletion(jobId, console.log, { pollInterval: 2000, maxAttempts: 60 });
 clearTimeout(timeout);
 ```
 
----
-
-## API Reference
+## Related Skills
 
-Consult the `bankr-api-basics` skill for:
-- Complete endpoint documentation
-- Authentication details
-- Response field descriptions
-- Error codes and handling
+Consult `bankr-api-basics` for complete endpoint documentation, authentication details, and error codes.
diff --git a/bankr-agent/skills/bankr-error-handling/SKILL.md b/bankr-agent/skills/bankr-error-handling/SKILL.md
index cabb7dc..c6c4071 100644
--- a/bankr-agent/skills/bankr-error-handling/SKILL.md
+++ b/bankr-agent/skills/bankr-error-handling/SKILL.md
@@ -1,40 +1,42 @@
 ---
-name: Bankr Agent - Error Handling
-description: This skill should be used when encountering authentication errors, API key errors, 401 errors, "invalid API key", "BANKR_API_KEY not set", job failures, or any Bankr API errors. Provides setup instructions and troubleshooting guidance for resolving Bankr configuration issues.
-version: 1.0.0
+name: bankr-error-handling
+description: "Use when encountering Bankr API errors including 401 authentication failures, invalid or missing API keys, BANKR_API_KEY not set errors, job failures (insufficient balance, slippage, reverts), rate limiting (429), or any HTTP error from api.bankr.bot. Provides step-by-step troubleshooting and user-facing error communication patterns."
 ---
 
 # Bankr Error Handling
 
-Resolve Bankr API errors and authentication issues.
+Diagnose and resolve Bankr API errors, authentication issues, and job failures.
 
-## Authentication Errors (401)
+## Workflow
 
-### Symptoms
-- HTTP 401 status code
-- "Invalid API key" or "Unauthorized" message
+1. Identify the error type (HTTP status code or job failure message)
+2. Follow the matching resolution below
+3. Present clear, jargon-free fix steps to the user
+4. Do NOT retry automatically when authentication fails — the user must fix their API key first
 
-### Resolution
+## Authentication Errors (401)
 
-Present these setup instructions to the user:
+**Symptoms:** HTTP 401, "Invalid API key", "Unauthorized"
 
-**Step 1: Create an API Key**
-```
-Visit https://bankr.bot/api to create a new API key
-```
+Present these setup steps to the user:
 
-**Step 2: Set Environment Variable**
-```bash
-# Add to shell profile (~/.zshrc or ~/.bashrc)
-export BANKR_API_KEY=bk_your_api_key_here
-```
+1. Visit https://bankr.bot/api to create a new API key
+2. Set the environment variable:
+   ```bash
+   # Add to ~/.zshrc or ~/.bashrc
+   export BANKR_API_KEY=bk_your_api_key_here
+   ```
+3. Restart the terminal / Claude Code session
 
-**Step 3: Restart Claude Code**
-```
-Close and reopen the terminal/Claude Code session
-```
+## HTTP Status Codes
 
-**Important**: Do NOT retry when authentication fails. User must fix API key first.
+| Code | Meaning | Action |
+|------|---------|--------|
+| 400 | Bad request | Check prompt format |
+| 401 | Unauthorized | Fix API key (see above) |
+| 402 | Payment required | Ensure wallet has BNKR on Base |
+| 429 | Rate limited | Wait and retry |
+| 500 | Server error | Retry after delay |
 
 ## Common Job Failures
 
@@ -46,30 +48,17 @@ Close and reopen the terminal/Claude Code session
 | Transaction reverted | On-chain failure | Check transaction details |
 | Rate limit exceeded | Too many requests | Wait and retry |
 
-## HTTP Status Codes
-
-| Code | Meaning | Action |
-|------|---------|--------|
-| 400 | Bad request | Check prompt format |
-| 401 | Unauthorized | Fix API key (see above) |
-| 402 | Payment required | Ensure wallet has BNKR on Base |
-| 429 | Rate limited | Wait and retry |
-| 500 | Server error | Retry after delay |
-
 ## Troubleshooting Checklist
 
-1. **API Key**: Set, starts with `bk_`, Claude Code restarted after setting
-2. **Network**: Internet working, api.bankr.bot reachable
-3. **For Trading**: Wallet has sufficient balance, token exists on chain
+1. **API Key** — set in environment, starts with `bk_`, Claude Code restarted after setting
+2. **Network** — internet working, api.bankr.bot reachable
+3. **For Trading** — wallet has sufficient balance, token exists on target chain
 
 ## Reporting Errors to Users
 
-1. State what went wrong simply
-2. Provide specific fix steps
-3. Avoid technical jargon
-4. Suggest alternatives
+Always: state what went wrong simply, provide specific fix steps, avoid technical jargon, suggest alternatives.
 
-**Example**:
+**Example:**
 ```
 Your Bankr API key is not configured. To set it up:
 1. Visit https://bankr.bot/api to create an API key
diff --git a/bankr-agent/skills/bankr-safety/SKILL.md b/bankr-agent/skills/bankr-safety/SKILL.md
index 9a71829..0eb34fe 100644
--- a/bankr-agent/skills/bankr-safety/SKILL.md
+++ b/bankr-agent/skills/bankr-safety/SKILL.md
@@ -1,16 +1,22 @@
 ---
-name: Bankr Agent - Safety & Access Control
-description: This skill should be used when the user asks about "API key security", "read-only key", "IP whitelist", "rate limits", "dedicated wallet", "agent wallet", "key rotation", "access control", or any safety, security, or access control topic related to Bankr.
-version: 1.0.0
+name: bankr-safety
+description: "Use when configuring Bankr API key security, setting up read-only keys, enabling IP whitelisting, managing rate limits, creating dedicated agent wallets, rotating keys, or addressing any safety and access control topic for Bankr API and CLI integrations."
 ---
 
-# Safety & Access Control
+# Bankr Safety & Access Control
 
-Comprehensive safety guidance for using the Bankr API and CLI.
+Security best practices and access control configuration for the Bankr API and CLI.
 
-## API Key Types
+## Workflow
 
-Bankr uses a single key format (`bk_...`) with capability flags:
+1. Set up API key with appropriate capability flags
+2. Configure access restrictions (read-only, IP whitelist) based on use case
+3. Create a dedicated agent wallet for autonomous agents
+4. Follow the pre-deployment checklist before going live
+
+## API Key Capability Flags
+
+Bankr uses a single key format (`bk_...`) with capability flags managed at [bankr.bot/api](https://bankr.bot/api):
 
 | Flag | Controls | Default |
 |------|----------|---------|
@@ -18,41 +24,27 @@ Bankr uses a single key format (`bk_...`) with capability flags:
 | `llmGatewayEnabled` | LLM Gateway at `llm.bankr.bot` | false |
 | `readOnly` | Restricts agent to read-only tools | false |
 
-Manage flags at [bankr.bot/api](https://bankr.bot/api).
-
-## Read-Only API Keys
-
-When `readOnly: true`, all write tools are filtered from the agent session:
+## Read-Only Keys
 
-**Allowed:** Balances, prices, analytics, portfolio, research
-**Blocked:** Swaps, transfers, NFT purchases, staking, orders, token launches, leverage, Polymarket bets, claims
+When `readOnly: true`, write tools are filtered from the agent session:
 
-The `/agent/sign` and `/agent/submit` endpoints return 403 for read-only keys.
+- **Allowed:** balances, prices, analytics, portfolio, research
+- **Blocked:** swaps, transfers, NFT purchases, staking, orders, token launches, leverage, Polymarket bets, claims
+- `/agent/sign` and `/agent/submit` return 403 for read-only keys
 
 ## IP Whitelisting
 
-Set `allowedIps` on your API key to restrict usage to specific IPs. Requests from non-whitelisted IPs are rejected with 403.
-
-- Empty array = all IPs allowed (default)
-- Non-empty array = only listed IPs can use the key
+Set `allowedIps` on your API key to restrict to specific IPs (403 for non-listed). Empty array = all IPs allowed (default).
 
 ## Dedicated Agent Wallet
 
-When building autonomous agents, create a **separate Bankr account** rather than using your personal wallet:
+For autonomous agents, create a **separate Bankr account** instead of using a personal wallet:
 
-- **Limited exposure** — compromised key only exposes agent wallet funds
+- **Limited exposure** — compromised key only affects agent wallet funds
 - **Clear accounting** — agent transactions isolated from personal activity
-- **Independent controls** — apply stricter access controls without affecting personal use
 - **Easy revocation** — disable agent account without disrupting primary wallet
 
-### Recommended Funding
-
-| Chain | Gas Buffer | Trading Capital |
-|-------|-----------|-----------------|
-| Base | 0.01-0.05 ETH | As needed |
-| Polygon | 5-10 MATIC | As needed |
-| Ethereum | 0.05-0.1 ETH | As needed |
-| Solana | 0.1-0.5 SOL | As needed |
+Recommended gas buffers: Base 0.01–0.05 ETH, Polygon 5–10 MATIC, Ethereum 0.05–0.1 ETH, Solana 0.1–0.5 SOL.
 
 ## Rate Limits
 
@@ -62,30 +54,22 @@ When building autonomous agents, create a **separate Bankr account** rather than
 | Bankr Club | 1,000 messages/day |
 | Custom | Set per API key |
 
-Reset window is 24 hours from first message (rolling), not midnight.
+Reset window is 24 hours rolling from first message, not midnight.
 
 ## Key Management
 
 - Store keys in environment variables (`BANKR_API_KEY`, `BANKR_LLM_KEY`), never in source code
 - Add `~/.bankr/` and `.env` to `.gitignore`
-- Rotate keys periodically at [bankr.bot/api](https://bankr.bot/api)
-- Revoke immediately if compromised
-- Use separate keys for Agent API vs LLM Gateway if needed
-
-## Transaction Safety
-
-- **Test first** — small amounts on Base/Polygon before scaling
-- **Verify recipients** — double-check addresses before transfers
-- **Gas buffer** — keep enough native tokens for gas
-- **Immediate execution** — `/agent/submit` executes with no confirmation prompt
-- **Understand calldata** — verify trusted source for arbitrary transactions
+- Rotate keys periodically at [bankr.bot/api](https://bankr.bot/api); revoke immediately if compromised
+- Use separate keys for Agent API vs LLM Gateway when needed
 
 ## Pre-Deployment Checklist
 
-- Use a dedicated agent wallet, not your personal account
-- Fund with limited amounts appropriate to purpose
-- Set read-only if agent only queries data
-- Configure IP whitelisting for server-side agents
-- Store keys in environment variables
-- Test with small amounts first
-- Implement error handling for rate limits (429) and access control (403)
+1. Use a dedicated agent wallet, not your personal account
+2. Fund with limited amounts appropriate to purpose
+3. Set read-only if agent only queries data
+4. Configure IP whitelisting for server-side agents
+5. Store keys in environment variables
+6. Test with small amounts on Base/Polygon before scaling
+7. Implement error handling for rate limits (429) and access control (403)
+8. Verify recipients and understand calldata before arbitrary transactions
diff --git a/bankr-agent/skills/bankr-token-trading/SKILL.md b/bankr-agent/skills/bankr-token-trading/SKILL.md
index a4d7350..1fcd30d 100644
--- a/bankr-agent/skills/bankr-token-trading/SKILL.md
+++ b/bankr-agent/skills/bankr-token-trading/SKILL.md
@@ -1,12 +1,18 @@
 ---
-name: Bankr Agent - Token Trading
-description: This skill should be used when the user asks to "buy crypto", "sell tokens", "swap ETH", "trade on Base", "exchange tokens", "cross-chain swap", "bridge tokens", "convert ETH to WETH", or any token trading operation. Provides guidance on supported chains, amount formats, and swap operations.
-version: 1.0.0
+name: bankr-token-trading
+description: "Use when executing token swaps, buying or selling crypto, bridging tokens cross-chain, or converting ETH to WETH via the Bankr agent. Covers supported chains (Base, Polygon, Ethereum, Unichain, Solana), amount formats (USD, percentage, exact), slippage handling, and common trading errors."
 ---
 
 # Bankr Token Trading
 
-Execute token trades and swaps across multiple blockchains.
+Execute token trades, swaps, and cross-chain bridges across multiple blockchains via the Bankr agent.
+
+## Workflow
+
+1. Construct a natural language prompt specifying the trade (token, amount, chain)
+2. Bankr selects the optimal route and executes the swap
+3. Monitor job status for completion or failure
+4. Handle errors per the common issues table below
 
 ## Supported Chains
 
@@ -18,6 +24,8 @@ Execute token trades and swaps across multiple blockchains.
 | Unichain | ETH |
 | Solana | SOL |
 
+If no chain is specified, Bankr selects the most appropriate (Base preferred for low fees). Cross-chain routes are automatically optimized.
+
 ## Amount Formats
 
 | Format | Example | Description |
@@ -41,18 +49,9 @@ Execute token trades and swaps across multiple blockchains.
 - "Convert 0.1 ETH to WETH"
 - "Unwrap 0.5 WETH to ETH"
 
-## Chain Selection
-
-- If no chain specified, Bankr selects the most appropriate chain
-- Base is preferred for most operations due to low fees
-- Cross-chain routes are automatically optimized
-- Include chain name in prompt to specify: "Buy ETH on Polygon"
-
 ## Slippage
 
-- Default slippage tolerance is applied automatically
-- For volatile tokens, Bankr adjusts slippage as needed
-- If slippage is exceeded, the transaction fails safely
+Default slippage tolerance is applied automatically. For volatile tokens, Bankr adjusts as needed. If slippage is exceeded, the transaction fails safely — no funds are lost.
 
 ## Common Issues
 
diff --git a/x402-sdk-dev/skills/sdk-balance-queries/SKILL.md b/x402-sdk-dev/skills/sdk-balance-queries/SKILL.md
index 6a1f98d..57bf839 100644
--- a/x402-sdk-dev/skills/sdk-balance-queries/SKILL.md
+++ b/x402-sdk-dev/skills/sdk-balance-queries/SKILL.md
@@ -1,14 +1,19 @@
 ---
-name: Bankr x402 SDK - Balance Queries
-description: This skill should be used when the user asks "what are my balances", "how much ETH do I have", "check my wallet", "show my tokens", "portfolio value", "what tokens do I own", "NFT holdings", "how much USDC", "get token balances", "wallet contents", or any question about token balances, wallet contents, portfolio values, or NFT holdings across chains using the Bankr SDK.
-version: 1.1.0
+name: sdk-balance-queries
+description: "Use when querying token balances, portfolio values, wallet contents, or NFT holdings across chains with the Bankr x402 SDK. Covers single-token, multi-token, multi-chain, and USD-denominated balance queries via natural language prompts and the BankrClient.promptAndWait() method."
 ---
 
 # SDK Balance Queries
 
-Query multi-chain token balances and portfolio data using natural language prompts.
+Query multi-chain token balances, portfolio values, and NFT holdings using natural language prompts via the Bankr x402 SDK.
 
-## Operations
+## Workflow
+
+1. Initialize `BankrClient` with a private key
+2. Call `client.promptAndWait({ prompt })` with a natural language balance query
+3. Parse `result.response` for balance data
+
+## Supported Operations
 
 | Operation | Example Prompt | Notes |
 |-----------|----------------|-------|
@@ -25,24 +30,20 @@ Query multi-chain token balances and portfolio data using natural language promp
 
 ```
 # Token Balances
-"What are my token balances?"
 "How much [TOKEN] do I have?"
 "Show my [TOKEN] balance on [CHAIN]"
 "What's my balance of token 0x..."
 
 # Multi-Chain
 "Show my balances across all chains"
-"What are my balances on Base and Ethereum?"
 "Compare my USDC holdings across all chains"
 
 # Portfolio Value
 "What's my total portfolio value in USD?"
-"How much is my [TOKEN] worth in USD?"
 "What's the total value of my Base holdings?"
 
 # NFTs
 "Show me my NFT collections"
-"How many Pudgy Penguins do I own?"
 "What's the floor price of my NFTs?"
 ```
 
@@ -72,9 +73,9 @@ console.log(result.response);
 | Polygon | L2 tokens and NFTs |
 | Solana | SPL tokens and NFTs |
 
-Specify chain in prompt: "on Base", "on Ethereum", "on Polygon", "on Solana"
+Specify chain in prompt: "on Base", "on Ethereum", "on Polygon", "on Solana".
 
 ## Related Skills
 
-- **sdk-wallet-operations**: Client setup and configuration
-- **sdk-capabilities**: Full list of supported operations
+- **sdk-wallet-operations** — client setup and configuration
+- **sdk-capabilities** — full list of supported operations