metamask-agent-workflows

MetaMask Agent Workflows

Repeatable multi-step patterns for the mm CLI. Load a workflow file when the user's request is a pattern, not a single command.

Workflow Routing

Pattern	Workflow
First time setup and onboarding	onboarding.md
Login flow	login.md
Troubleshooting decision tree	troubleshooting.md
Swap quote-review-execute flow	swap.md
Bridge quote-review-execute flow	bridge.md
Open a perpetual position flow	perps-open-position.md
Close a perpetual position flow	perps-close-position.md
Modify a perpetual position flow	perps-modify-position.md
Predict first-time setup and credentials	predict-setup.md
Deposit or withdraw pUSD from Predict wallet	predict-funding.md
Search and browse prediction markets	predict-markets.md
Quote and place a prediction order	predict-place-order.md
View or cancel Predict orders and positions	predict-manage-orders.md
View Predict portfolio and redeem winnings	predict-portfolio.md
Token discovery, prices, and market data	market-data.md
Supply assets to Aave V3	aave-supply.md
Withdraw assets from Aave V3	aave-withdraw.md
Borrow from Aave V3	aave-borrow.md
Repay Aave V3 debt	aave-repay.md
Toggle Aave V3 collateral	aave-collateral.md
Check Aave V3 positions and health factor	aave-positions.md
Discover Aave V3 tokens, rates, and liquidity	aave-markets.md

Always use --toon for command output unless the user explicitly requests a different format.

Preflight

Run these checks before the first CLI operation in a session, in order.

1. Version compatibility

This skill is written for @metamask/agentic-cli v4.0.0 (see cliVersion in the frontmatter). Check the installed version:

mm --version

The installed version is the value after @metamask/agentic-cli/ (e.g. @metamask/agentic-cli/2.0.0 darwin-arm64 node-v22.18.0). Compare its major.minor against the pinned cliVersion. Optionally check the latest published version (best-effort; skip silently on network failure):

npm view @metamask/agentic-cli version

If the installed major.minor differs from the pinned cliVersion, or the installed version is behind the latest release, warn the user once and continue:

Version mismatch: installed CLI <installed>, this skill is pinned to 4.0.0, latest release is <latest>. Command syntax in this skill may be inaccurate until they are aligned. Update the CLI with npm install -g @metamask/agentic-cli@latest, then re-install the skills with npx skills add metaMask/agent-skills.

Run this check once per session. Do not block operations on it.

2. Readiness gate (authentication + initialization)

mm doctor is the single readiness check. Run it before the first CLI operation in a session:

mm doctor

It reports an authenticated boolean, an initialized boolean, and a list of hints. Do not run any other command until mm doctor reports both authenticated: true and initialized: true. Authentication and initialization are independent gates: a session can be authenticated while the project has no wallet mode selected, in which case any command that needs a wallet aborts before running with NOT_INITIALIZED — "Project not initialized." (hint: Run mm init to set up wallet and trading modes.).

A project counts as initialized only when a wallet mode is set — and, for server-wallet, a trading mode is set as well (byok needs only the wallet mode). Do not use mm init show as the check: it requires an initialized project and throws NOT_INITIALIZED on an uninitialized one rather than reporting state.

Remediate, then re-run mm doctor and confirm a clean result before doing anything else:

• authenticated: false → follow workflows/login.md (or workflows/onboarding.md for first-time setup) to run mm login.
• authenticated: true and initialized: false → follow workflows/onboarding.md to run mm init and select a wallet mode (and a trading mode for server-wallet).

Command Discovery

Before constructing any command, run mm <command> --help to confirm the exact flags, syntax, and defaults. Do not guess flags from memory.

Output Rules

• Route silently. Do not announce which workflow you are loading.
• Surface errors from commands verbatim. Do not mask or reword them.
• If a command fails, check mm <command> --help and guide from there.