refactor(metamask-connect): consolidate into progressive-disclosure skills

adonesky1 · adonesky1 · commit e522683e01fa · 2026-06-15T12:10:34.000-05:00
Collapses the 18 granular per-chain/platform/operation skills into 5
task-oriented skills, each with a thin routing skill.md that points into a
references/ library (mirrors the domains/performance pattern):

- setup-app           (9 references: evm/solana x browser/react/react-native, multichain, wagmi, wagmi-connector)
- sign-message        (evm, solana)
- send-transaction    (evm, solana)
- multichain-operations (evm, solana — invokeMethod sign/send)
- migrate             (from-sdk, wagmi-connector)

troubleshoot-connection and metamask-connect-conventions are unchanged.
Original (source-verified) bodies move verbatim into references; only stale
cross-skill mentions were rewritten. Addresses review feedback to favor
progressive disclosure and composability.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Add `metamask-connect` domain: 18 skills for building dApps with the MetaMask Connect SDK (`@metamask/connect-evm`, `@metamask/connect-multichain`, `@metamask/connect-solana`) across EVM, Solana, multichain, wagmi, and React Native, plus signing, transaction, migration, and troubleshooting skills, and a `metamask-connect-conventions` guardrails skill
+- Add `metamask-connect` domain for building dApps with the MetaMask Connect SDK (`@metamask/connect-evm`, `@metamask/connect-multichain`, `@metamask/connect-solana`) and the wagmi `metaMask()` connector. Organized with progressive disclosure as `setup-app`, `sign-message`, `send-transaction`, `multichain-operations`, and `migrate` (each routing into per-stack `references/`), plus `troubleshoot-connection` and a `metamask-connect-conventions` guardrails skill
 
 ## [0.1.0]
 
diff --git a/domains/metamask-connect/skills/migrate/references/from-sdk.md b/domains/metamask-connect/skills/migrate/references/from-sdk.md
@@ -1,8 +1,3 @@
----
-name: migrate-from-sdk
-description: Migrate from @metamask/sdk to @metamask/connect-evm, @metamask/connect-multichain, and @metamask/connect-solana with step-by-step package, API, and configuration changes
-maturity: stable
----
 # Migrate from @metamask/sdk to @metamask/connect
 
 ## When to use
@@ -315,7 +310,7 @@ Key differences:
 - The connect-evm-backed `metaMask()` connector ships in `wagmi/connectors` from wagmi 3.6 / `@wagmi/connectors` 8 — there is no `@metamask/connect-evm/wagmi` subpath; install `@metamask/connect-evm` at wagmi's declared peer range
 - Use `dapp` not `dappMetadata`
 - Connector ID is `'metaMaskSDK'` — find it with `connectors.find(c => c.id === 'metaMaskSDK')`
-- Most wagmi hooks work unchanged, but note the wagmi v3 renames: `useConnect().connectors` → `useConnectors()`, `connectAsync` → `mutateAsync`, `useAccount` → `useConnection` (see the migrate-wagmi-metamask-connector skill)
+- Most wagmi hooks work unchanged, but note the wagmi v3 renames: `useConnect().connectors` → `useConnectors()`, `connectAsync` → `mutateAsync`, `useAccount` → `useConnection` (see `references/wagmi-connector.md`)
 
 ---
 
diff --git a/domains/metamask-connect/skills/migrate/references/wagmi-connector.md b/domains/metamask-connect/skills/migrate/references/wagmi-connector.md
@@ -1,8 +1,3 @@
----
-name: migrate-wagmi-metamask-connector
-description: Migrate a wagmi app from @metamask/sdk to the new @metamask/connect-evm connector (wagmi PR #4960)
-maturity: stable
----
 # Migrate Wagmi MetaMask Connector to @metamask/connect-evm
 
 ## When to use
diff --git a/domains/metamask-connect/skills/migrate/skill.md b/domains/metamask-connect/skills/migrate/skill.md
@@ -0,0 +1,17 @@
+---
+name: migrate
+description: Migrate an existing MetaMask integration to the MetaMask Connect SDK — from @metamask/sdk to @metamask/connect-evm / -multichain / -solana with step-by-step package, API, and config changes, or a wagmi app to the new connect-evm metaMask() connector. Routes to per-path references.
+maturity: stable
+---
+# Migrate to the MetaMask Connect SDK
+
+## When to use
+
+Use this when **moving an existing app** onto the MetaMask Connect SDK.
+
+| Migrating from | Reference |
+|----------------|-----------|
+| `@metamask/sdk` → `@metamask/connect-*` | [`references/from-sdk.md`](references/from-sdk.md) |
+| wagmi app → the new `@metamask/connect-evm` connector | [`references/wagmi-connector.md`](references/wagmi-connector.md) |
+
+After migrating, follow the `metamask-connect-conventions` skill to catch behavior differences (singleton behavior, event payloads, hex chain IDs).
diff --git a/domains/metamask-connect/skills/multichain-operations/references/evm.md b/domains/metamask-connect/skills/multichain-operations/references/evm.md
@@ -1,8 +1,3 @@
----
-name: sign-multichain-evm-transaction
-description: Sign and send EVM transactions using the multichain client's invokeMethod. Covers eth_sendTransaction, personal_sign, eth_signTypedData_v4, scope selection, and RPC routing for read vs sign operations.
-maturity: stable
----
 # Sign EVM Transactions via Multichain Client
 
 ## When to use
diff --git a/domains/metamask-connect/skills/multichain-operations/references/solana.md b/domains/metamask-connect/skills/multichain-operations/references/solana.md
@@ -1,8 +1,3 @@
----
-name: sign-multichain-solana-transaction
-description: Sign and send Solana transactions using the multichain client's invokeMethod. Covers signTransaction, signAndSendTransaction, signMessage, building transactions with @solana/web3.js, base64 encoding, mainnet/devnet scopes, and selective disconnect.
-maturity: stable
----
 # Sign Solana Transactions via Multichain Client
 
 ## When to use
diff --git a/domains/metamask-connect/skills/multichain-operations/skill.md b/domains/metamask-connect/skills/multichain-operations/skill.md
@@ -0,0 +1,17 @@
+---
+name: multichain-operations
+description: Sign and send transactions and messages through the MetaMask Connect multichain client's invokeMethod — EVM (eth_sendTransaction, personal_sign, eth_signTypedData_v4) and Solana (signTransaction, signAndSendTransaction, signMessage). Use after createMultichainClient when performing operations across CAIP-2 scopes, including building Solana transactions with @solana/web3.js, base64 encoding, mainnet/devnet scope selection, RPC routing for read vs sign, and selective disconnect. Routes to per-ecosystem references.
+maturity: stable
+---
+# Operations via the MetaMask Connect Multichain Client
+
+## When to use
+
+Use this when you created a **multichain** client (`createMultichainClient`, see the `setup-app` skill → `references/multichain.md`) and need to **sign or send** across CAIP-2 scopes with `invokeMethod`. For the single-chain `createEVMClient` / `createSolanaClient` paths, use the `sign-message` and `send-transaction` skills instead.
+
+| Ecosystem | Reference |
+|-----------|-----------|
+| EVM scopes (`eth_sendTransaction`, `personal_sign`, `eth_signTypedData_v4`) | [`references/evm.md`](references/evm.md) |
+| Solana scopes (`signTransaction`, `signAndSendTransaction`, `signMessage`) | [`references/solana.md`](references/solana.md) |
+
+Follow the `metamask-connect-conventions` skill, especially the multichain session-lifecycle guardrails.
diff --git a/domains/metamask-connect/skills/send-transaction/references/evm.md b/domains/metamask-connect/skills/send-transaction/references/evm.md
@@ -1,8 +1,3 @@
----
-name: send-evm-transaction
-description: Send ETH and contract transactions with MetaMask using eth_sendTransaction via the EIP-1193 provider, gas estimation, receipt polling, and the connectWith shortcut
-maturity: stable
----
 # Send EVM Transactions with MetaMask Connect
 
 ## When to use
diff --git a/domains/metamask-connect/skills/send-transaction/references/solana.md b/domains/metamask-connect/skills/send-transaction/references/solana.md
@@ -1,8 +1,3 @@
----
-name: send-solana-transaction
-description: Build and send a Solana transaction using MetaMask Connect. Covers both the React wallet-adapter approach (sendTransaction) and the vanilla browser approach (signAndSendTransaction wallet-standard feature).
-maturity: stable
----
 # Send Solana Transaction with MetaMask
 
 ## When to use
@@ -47,7 +42,7 @@ transaction.feePayer = senderPubkey;
 
 ### Step 2a: Send with React wallet-adapter (useWallet)
 
-**Prerequisites:** `createSolanaClient` has been awaited before rendering, `WalletProvider` is configured with `wallets={[]}`, and the user is connected. See the `setup-solana-react-app` skill.
+**Prerequisites:** `createSolanaClient` has been awaited before rendering, `WalletProvider` is configured with `wallets={[]}`, and the user is connected. See the `setup-app` skill (`references/solana-react.md`).
 
 ```tsx
 import { useWallet, useConnection } from '@solana/wallet-adapter-react';
@@ -102,7 +97,7 @@ function SendTransactionButton() {
 
 ### Step 2b: Send with vanilla browser (wallet-standard feature)
 
-**Prerequisites:** `createSolanaClient` has been called and the wallet is connected via `standard:connect`. See the `setup-solana-browser-app` skill.
+**Prerequisites:** `createSolanaClient` has been called and the wallet is connected via `standard:connect`. See the `setup-app` skill (`references/solana-browser.md`).
 
 ```typescript
 import { createSolanaClient } from '@metamask/connect-solana';
diff --git a/domains/metamask-connect/skills/send-transaction/skill.md b/domains/metamask-connect/skills/send-transaction/skill.md
@@ -0,0 +1,17 @@
+---
+name: send-transaction
+description: Send transactions with MetaMask in a dApp — EVM (eth_sendTransaction with gas estimation and receipt polling, plus the connectWith shortcut) and Solana (React wallet-adapter sendTransaction or vanilla signAndSendTransaction). Use when submitting on-chain transactions. Routes to per-chain references. For sending through the multichain client's invokeMethod, see the multichain-operations skill.
+maturity: stable
+---
+# Send Transactions with MetaMask Connect
+
+## When to use
+
+Use this to **submit an on-chain transaction** with a directly-created EVM or Solana client. If you set up the **multichain** client (`createMultichainClient`), send via `invokeMethod` instead — see the `multichain-operations` skill.
+
+| Chain | Reference |
+|-------|-----------|
+| EVM (`eth_sendTransaction`, gas, receipts, `connectWith`) | [`references/evm.md`](references/evm.md) |
+| Solana (`sendTransaction` / `signAndSendTransaction`) | [`references/solana.md`](references/solana.md) |
+
+Follow the `metamask-connect-conventions` skill for provider/error-handling guardrails.
diff --git a/domains/metamask-connect/skills/setup-app/references/evm-browser.md b/domains/metamask-connect/skills/setup-app/references/evm-browser.md
@@ -1,8 +1,3 @@
----
-name: setup-evm-browser-app
-description: Scaffold a vanilla JS/TS browser app with MetaMask EVM integration using createEVMClient, EIP-1193 provider event listeners, RPC methods, and chain switching with chainConfiguration fallback
-maturity: stable
----
 # Setup EVM Browser App with MetaMask Connect
 
 ## When to use
diff --git a/domains/metamask-connect/skills/setup-app/references/evm-react-native.md b/domains/metamask-connect/skills/setup-app/references/evm-react-native.md
@@ -1,8 +1,3 @@
----
-name: setup-evm-react-native-app
-description: Scaffold a React Native app with MetaMask EVM integration including required polyfills, metro.config.js shims, import order constraints, mobile deeplinks, and a full component example
-maturity: stable
----
 # Setup EVM React Native App with MetaMask Connect
 
 ## When to use
diff --git a/domains/metamask-connect/skills/setup-app/references/evm-react.md b/domains/metamask-connect/skills/setup-app/references/evm-react.md
@@ -1,8 +1,3 @@
----
-name: setup-evm-react-app
-description: Scaffold a React app with MetaMask EVM integration using createEVMClient, useState/useEffect/useRef patterns, provider.request calls, chain switching, and error handling
-maturity: stable
----
 # Setup EVM React App with MetaMask Connect
 
 ## When to use
diff --git a/domains/metamask-connect/skills/setup-app/references/multichain.md b/domains/metamask-connect/skills/setup-app/references/multichain.md
@@ -1,8 +1,3 @@
----
-name: setup-multichain-app
-description: Set up a multichain app using createMultichainClient from @metamask/connect-multichain. Covers EVM + Solana scopes, invokeMethod for both ecosystems, session events, headless mode, getInfuraRpcUrls, selective disconnect, and singleton behavior.
-maturity: stable
----
 # Setup Multichain App with MetaMask
 
 ## When to use
diff --git a/domains/metamask-connect/skills/setup-app/references/solana-browser.md b/domains/metamask-connect/skills/setup-app/references/solana-browser.md
@@ -1,8 +1,3 @@
----
-name: setup-solana-browser-app
-description: Set up a vanilla browser (non-React) app with @metamask/connect-solana using wallet-standard features directly. Use when integrating MetaMask Solana without a framework or wallet adapter library.
-maturity: stable
----
 # Setup Solana Browser App with MetaMask
 
 ## When to use
diff --git a/domains/metamask-connect/skills/setup-app/references/solana-react-native.md b/domains/metamask-connect/skills/setup-app/references/solana-react-native.md
@@ -1,8 +1,3 @@
----
-name: setup-solana-react-native-app
-description: Set up a React Native app with @metamask/connect-solana using polyfills and multichain invokeMethod for Solana operations. Use when building Solana support in React Native where wallet-adapter is not available.
-maturity: stable
----
 # Setup Solana React Native App with MetaMask
 
 ## When to use
diff --git a/domains/metamask-connect/skills/setup-app/references/solana-react.md b/domains/metamask-connect/skills/setup-app/references/solana-react.md
@@ -1,8 +1,3 @@
----
-name: setup-solana-react-app
-description: Set up a React app with @metamask/connect-solana and the Solana wallet adapter. Use when integrating MetaMask with Solana in React, configuring WalletProvider, or building connect/sign/send flows with useWallet.
-maturity: stable
----
 # Setup Solana React App with MetaMask
 
 ## When to use
diff --git a/domains/metamask-connect/skills/setup-app/references/wagmi-connector.md b/domains/metamask-connect/skills/setup-app/references/wagmi-connector.md
@@ -1,8 +1,3 @@
----
-name: setup-wagmi-metamask-connector
-description: Set up a wagmi app with the MetaMask Connect EVM connector using @metamask/connect-evm
-maturity: stable
----
 # Set Up Wagmi with MetaMask Connect EVM Connector
 
 ## When to use
diff --git a/domains/metamask-connect/skills/setup-app/references/wagmi.md b/domains/metamask-connect/skills/setup-app/references/wagmi.md
@@ -1,8 +1,3 @@
----
-name: setup-wagmi-app
-description: Set up a React or React Native app with wagmi and a MetaMask connector implementation that matches your installed @metamask/connect-evm version. Use when integrating MetaMask with wagmi, configuring the metaMask() connector, or building connect/sign/send flows.
-maturity: stable
----
 # Setup wagmi App with MetaMask
 
 ## When to use
diff --git a/domains/metamask-connect/skills/setup-app/skill.md b/domains/metamask-connect/skills/setup-app/skill.md
@@ -0,0 +1,35 @@
+---
+name: setup-app
+description: Scaffold a dApp that integrates MetaMask via the MetaMask Connect SDK — EVM, Solana, or both (multichain) — across vanilla browser JS/TS, React, and React Native, or through wagmi. Use when starting a new MetaMask integration or wiring connect/disconnect and provider setup. Routes to per-stack references covering createEVMClient, createSolanaClient, createMultichainClient, and the wagmi metaMask() connector, including EIP-1193 provider events, chain switching with chainConfiguration, Solana wallet-standard, React Native polyfills, and metro config.
+maturity: stable
+---
+# Set Up a MetaMask Connect dApp
+
+## When to use
+
+Use this when you are **starting or wiring up** a dApp's MetaMask integration: choosing a Connect SDK package, creating the client, and getting connect/disconnect + the provider working. For signing, sending transactions, or migrating, see the `sign-message`, `send-transaction`, `multichain-operations`, and `migrate` skills.
+
+## 1. Choose your client
+
+| You need | Package | Then read |
+|----------|---------|-----------|
+| EVM only | `@metamask/connect-evm` (`createEVMClient`) | an `evm-*` reference below |
+| Solana only | `@metamask/connect-solana` (`createSolanaClient`) | a `solana-*` reference below |
+| EVM **and** Solana in one session | `@metamask/connect-multichain` (`createMultichainClient`) | `references/multichain.md` |
+| You already use wagmi | wagmi `metaMask()` connector | `references/wagmi.md` |
+
+## 2. Read the reference for your stack
+
+| Building | Reference |
+|----------|-----------|
+| EVM dApp — vanilla browser JS/TS | [`references/evm-browser.md`](references/evm-browser.md) |
+| EVM dApp — React | [`references/evm-react.md`](references/evm-react.md) |
+| EVM dApp — React Native | [`references/evm-react-native.md`](references/evm-react-native.md) |
+| Solana dApp — vanilla browser | [`references/solana-browser.md`](references/solana-browser.md) |
+| Solana dApp — React | [`references/solana-react.md`](references/solana-react.md) |
+| Solana dApp — React Native | [`references/solana-react-native.md`](references/solana-react-native.md) |
+| EVM + Solana (multichain) | [`references/multichain.md`](references/multichain.md) |
+| wagmi app | [`references/wagmi.md`](references/wagmi.md) |
+| wagmi + the connect-evm connector | [`references/wagmi-connector.md`](references/wagmi-connector.md) |
+
+Always apply the `metamask-connect-conventions` skill (hex chain IDs, singleton behavior, EIP-1193 events, Solana constraints, React Native polyfills) alongside whichever reference you follow.
diff --git a/domains/metamask-connect/skills/sign-message/references/evm.md b/domains/metamask-connect/skills/sign-message/references/evm.md
@@ -1,8 +1,3 @@
----
-name: sign-evm-message
-description: Sign messages with MetaMask using personal_sign and eth_signTypedData_v4 via the EIP-1193 provider, plus the connectAndSign shortcut
-maturity: stable
----
 # Sign EVM Messages with MetaMask Connect
 
 ## When to use
diff --git a/domains/metamask-connect/skills/sign-message/references/solana.md b/domains/metamask-connect/skills/sign-message/references/solana.md
@@ -1,8 +1,3 @@
----
-name: sign-solana-message
-description: Sign an arbitrary message on Solana using MetaMask Connect. Covers both the React wallet-adapter approach (useWallet) and the vanilla browser approach (wallet-standard features).
-maturity: stable
----
 # Sign Solana Message with MetaMask
 
 ## When to use
@@ -25,7 +20,7 @@ const message = new TextEncoder().encode('Sign this message to verify your ident
 
 ### Step 2a: Sign with React wallet-adapter (useWallet)
 
-**Prerequisites:** `createSolanaClient` has been awaited before rendering, `WalletProvider` is configured with `wallets={[]}`, and the user is connected. See the `setup-solana-react-app` skill.
+**Prerequisites:** `createSolanaClient` has been awaited before rendering, `WalletProvider` is configured with `wallets={[]}`, and the user is connected. See the `setup-app` skill (`references/solana-react.md`).
 
 ```tsx
 import { useWallet } from '@solana/wallet-adapter-react';
@@ -64,7 +59,7 @@ function SignMessageButton() {
 
 ### Step 2b: Sign with vanilla browser (wallet-standard feature)
 
-**Prerequisites:** `createSolanaClient` has been called and the wallet is connected via `standard:connect`. See the `setup-solana-browser-app` skill.
+**Prerequisites:** `createSolanaClient` has been called and the wallet is connected via `standard:connect`. See the `setup-app` skill (`references/solana-browser.md`).
 
 ```typescript
 import { createSolanaClient } from '@metamask/connect-solana';
diff --git a/domains/metamask-connect/skills/sign-message/skill.md b/domains/metamask-connect/skills/sign-message/skill.md
@@ -0,0 +1,17 @@
+---
+name: sign-message
+description: Sign arbitrary messages with MetaMask in a dApp — EVM (personal_sign, eth_signTypedData_v4, plus the connectAndSign shortcut) and Solana (wallet-standard signMessage, via React wallet-adapter or vanilla browser). Use when adding message signing or wallet authentication such as Sign-In With Ethereum or nonce signing. Routes to per-chain references. For signing through the multichain client's invokeMethod, see the multichain-operations skill.
+maturity: stable
+---
+# Sign Messages with MetaMask Connect
+
+## When to use
+
+Use this to **sign an arbitrary message** (authentication, Sign-In With Ethereum, nonce signing) with a directly-created EVM or Solana client. If you set up the **multichain** client (`createMultichainClient`), sign via `invokeMethod` instead — see the `multichain-operations` skill.
+
+| Chain | Reference |
+|-------|-----------|
+| EVM (`personal_sign`, `eth_signTypedData_v4`, `connectAndSign`) | [`references/evm.md`](references/evm.md) |
+| Solana (wallet-standard `signMessage`) | [`references/solana.md`](references/solana.md) |
+
+Follow the `metamask-connect-conventions` skill for provider/error-handling guardrails.
