Skip to content

feat: add metamask-connect agent skill (skills.sh)#334

Merged
adonesky1 merged 10 commits into
mainfrom
adonesky/add-metamask-connect-skill
Jun 18, 2026
Merged

feat: add metamask-connect agent skill (skills.sh)#334
adonesky1 merged 10 commits into
mainfrom
adonesky/add-metamask-connect-skill

Conversation

@adonesky1

@adonesky1 adonesky1 commented Jun 17, 2026

Copy link
Copy Markdown
Contributor

What

Adds a top-level skills/ directory with a single metamask-connect Agent Skill for building dApps with this SDK (@metamask/connect-evm, @metamask/connect-multichain, @metamask/connect-solana) and the wagmi metaMask() connector.

skills/metamask-connect/
  SKILL.md                       # routing: when-to-use + install + tables into references/ and workflows/
  references/
    conventions.md               # always-on guardrails (hex chain IDs, supportedNetworks, EIP-1193 events, RN polyfills, testing)
    troubleshooting.md           # symptom -> cause -> fix index + diagnostic checklist
  workflows/
    setup-{evm,solana}-{browser,react,react-native}.md
    setup-multichain.md  setup-wagmi.md  setup-wagmi-connector.md
    sign-{evm,solana}-message.md
    send-{evm,solana}-transaction.md
    multichain-{evm,solana}-operations.md
    migrate-from-sdk.md  migrate-wagmi-connector.md

Why colocate here

  • Stays in sync with the code. The skill versions with the SDK and can be updated in the same PR as an API change, reviewed by the same owners — the main defense against doc drift, which is the biggest risk for SDK skills.
  • External-dev install path. Installable via npx skills add MetaMask/connect-monorepo and tracked on skills.sh, matching the MetaMask embedded-wallets "build with AI" pattern.
  • Consistency. Mirrors Add SKILLs smart-accounts-kit#264, which is moving its skills out of MetaMask/skills into the SDK repo for the same reasons.

Format notes

  • Follows the Agent Skills spec: SKILL.md (uppercase), frontmatter name (matches the folder) + description, on-demand references/ + workflows/ linked by relative paths one level from SKILL.md.
  • references/conventions.md folds the MetaMask Connect Cursor plugin's always-on rules into one doc, so non-Cursor agents installing via npx skills still get the guardrails.
  • Not a workspace package — skills/ is outside the packages/*, playground/*, integrations/* globs, so it isn't built by turbo or published to npm.
  • Markdown formatted with the repo's prettier (yarn lint:misc clean).

Provenance

Ported from MetaMask/skills#50 (now closed in favor of colocation). Every workflow was source-verified against the published @metamask/connect-* packages.

Ownership

Covered by the existing * @MetaMask/wallet-integrations CODEOWNERS rule. Happy to add @MetaMask/mobile-platform as a co-owner of skills/ if preferred.

Notes

  • Agents from the source plugin (Cursor-specific personas) are intentionally not ported — Agent Skills has no agent concept.

@adonesky1
feat: add metamask-connect agent skill (skills.sh)
18157ea 
Colocate the MetaMask Connect SDK agent skill in the SDK repo so it
versions with the code and is installable via `npx skills add
MetaMask/connect-monorepo`, with skills.sh install analytics.

Single progressive-disclosure skill (Agent Skills format), mirroring
MetaMask/smart-accounts-kit#264: a routing SKILL.md points into
references/ (conventions, troubleshooting) and workflows/ (per-stack
setup, sign/send for EVM + Solana, multichain invokeMethod, migration).

Ported from MetaMask/skills#50 (now closed); source-verified against the
published @metamask/connect-* packages.
@adonesky1 adonesky1 requested a review from a team as a code owner June 17, 2026 14:56
@adonesky1 adonesky1 mentioned this pull request Jun 17, 2026
Closed
adonesky1 added 5 commits June 17, 2026 13:06
@adonesky1
docs(skills): fix stale wagmi connect-evm peer range and client wording
47f07ab 
- Correct the @wagmi/connectors metaMask() optional peer range from the
  stale ^1.3.0 to the current ^2.1.0 across setup-wagmi, setup-wagmi-connector,
  migrate-from-sdk, and migrate-wagmi-connector. The old guidance ("do not
  install 2.x") was inverted and would produce the peer mismatch it warned
  against; now points readers at `npm info @wagmi/connectors peerDependencies`.
- Fix setup-evm-react-native: createEVMClient is not a singleton (only the
  multichain core is); each call returns a fresh wrapper.
- Align Solana sign/send prerequisites with setup-solana-react: createSolanaClient
  need not resolve before first render (wallet registers ~1s later).
@adonesky1
docs(skills): add Content Security Policy guidance
558b87e 
Add a Content Security Policy section to conventions.md covering the
required relay WebSocket and QR data: URI origins, optional analytics /
Stencil style allowances, and a minimal example. Add pointers from the
browser-specific setup guides (EVM, Solana, multichain) and a dedicated
troubleshooting entry so a CSP-blocked relay (which presents as a hung
connection) is diagnosable.
@adonesky1
docs(skills): add Node.js (CLI / server) setup workflow
cf18425 
Add workflows/setup-node.md covering headless integration: terminal ASCII
QR connect via MetaMask Mobile, createMultichainClient as the recommended
Node entry point (connect-multichain/connect-solana ship node builds;
connect-evm delegates to the multichain node build), EVM/Solana signing
through invokeMethod, the in-memory default storage caveat (no persistence
across restarts) and how to supply a custom StoreClient, and the absence
of polyfill/CSP requirements. Wire it into SKILL.md with a routing row and
a "When to use" bullet.
@adonesky1
docs(skills): fix prettier formatting in setup-node.md
c1952d1 
Wrap the long Buffer.from(...).toString('base64') line in the Solana
invokeMethod example so it satisfies the repo's prettier (lint:misc)
80-col rule. Resolves the failing Lint CI job.
@adonesky1
docs(skills): split conventions.md into focused references; dedupe cr…
702ca6f 
…oss-cutting blocks

Reduce documentation drift surface by giving each topic a single canonical
home, per the Agent Skills guidance (focused reference files, TOCs >300
lines) and mirroring MetaMask/smart-accounts-kit#264's domain-split refs.

- Split the 610-line conventions.md into 7 focused, domain-organized
  references (evm, events, multichain, solana, react-native, csp, testing),
  each with its own table of contents. conventions.md is now a 93-line
  always-on core (import paths, config, supportedNetworks, singleton, error
  handling, connection state) plus a topic index routing to the rest.
- Repoint the CSP cross-links in setup-evm-browser, setup-solana-browser,
  setup-multichain, and troubleshooting at the new canonical csp.md.
- Point the two React Native setup workflows at react-native.md as the
  canonical polyfill/Metro reference (keeping their runnable recipes).
- Update SKILL.md's always-on pointer to describe the core + focused refs.

All skills/**/*.md pass prettier (3.6.2) and every internal link/anchor
resolves.
jiexi
jiexi reviewed Jun 18, 2026
View reviewed changes
Comment thread skills/metamask-connect/references/conventions.md Outdated
jiexi
jiexi reviewed Jun 18, 2026
View reviewed changes
Comment thread skills/metamask-connect/references/conventions.md Outdated
jiexi
jiexi reviewed Jun 18, 2026
View reviewed changes
Comment thread skills/metamask-connect/references/conventions.md Outdated
jiexi
jiexi reviewed Jun 18, 2026
View reviewed changes
Comment thread skills/metamask-connect/references/conventions.md Outdated
adonesky1 and others added 4 commits June 18, 2026 15:01
@adonesky1
docs(skills): fix dangling react-native-polyfills rule references
9e007f2 
Point migrate-from-sdk and setup-wagmi-connector workflows at the
existing references/react-native.md instead of a non-existent rule.
@adonesky1 @jiexi
Apply suggestions from code review
54e7d97 
Co-authored-by: jiexi <jiexiluan@gmail.com>
@adonesky1
docs(skills): clarify wagmi connector entrypoint and multichain dep
b24883f 
Address review feedback on conventions.md import-paths section:
- State that the wagmi metaMask() connector comes from wagmi/connectors
  with connect-evm as an optional peer; connect-evm ships no wagmi
  entrypoint.
- Trim the multichain dependency bullet: drop the imprecise ^1.0.0 pin
  and 2.0.0 history, keep the load-bearing "installed transitively" fact.
@adonesky1
docs(skills): tighten conventions, solana, events, and multichain refs
223eb0e 
Address review feedback:
- conventions: merge duplicate dapp.url bullets; add Solana disconnect
  scope behavior; enumerate the EVM methods that are rejected.
- solana: rewrite the Chrome Android note to be actionable (the
  wallet-adapter beforeunload patch is internal and not inherited by
  consumers); reframe the RN section as a third-party adapter limitation
  with the multichain/invokeMethod path.
- events: reframe intro so it doesn't read as EVM-only; add a Solana
  state-changes section pointing at core.stateChanged.
- multichain: trim the bundle/lazy-transport section to the one
  actionable guardrail.
@adonesky1 adonesky1 merged commit ddee296 into main Jun 18, 2026
20 checks passed
@adonesky1 adonesky1 deleted the adonesky/add-metamask-connect-skill branch June 18, 2026 21:07
@adonesky1 adonesky1 mentioned this pull request Jun 18, 2026
Merged
2 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jiexi jiexi jiexi approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@adonesky1 @jiexi