Add SKILLs

README.md

@@ -10,6 +10,9 @@ This monorepo consists of a suite of tools to enable developers to build using t
   - `/smart-accounts-kit` has utilities for creating a [DeleGator SCA](https://github.com/MetaMask/delegation-framework/blob/main/documents/DeleGatorCore.md#metamasks-delegatorcore) know as MetaMask smart account, setting up delegations, and redeeming them.
   - `/delegator-e2e` has end-to-end tests for the Smart Accounts Kit.
 - `./shared` contains basic shared resources for configuring and testing the packages.
+- `./skills` contains agent skills that help AI coding assistants use the Smart Accounts Kit correctly.
+  - [`/smart-accounts-kit`](./skills/smart-accounts-kit/SKILL.md) — build dApps with MetaMask Smart Accounts, ERC-7710 delegations, and ERC-7715 Advanced Permissions.
+  - [`/x402-payments`](./skills/x402-payments/SKILL.md) — build x402 (HTTP 402) machine-to-machine payment flows using ERC-7710 delegations and ERC-7715 Advanced Permissions.
 
 ## Getting Started
 

skills/smart-accounts-kit/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: smart-accounts-kit
+version: 1
+description: Build dApps with MetaMask Smart Accounts Kit — ERC-4337 smart accounts, delegations, and Advanced Permissions (ERC-7715)
+---
+
+# MetaMask Smart Accounts Kit
+
+## When to use
+
+- You want to create ERC-4337 smart accounts (Hybrid, MultiSig, or Stateless7702)
+- You want to send user operations or batch transactions via bundlers
+- You want to configure signers (EOA, passkey/WebAuthn, multisig, wallet client)
+- You want to implement gas abstraction with paymasters
+- You want to create, sign, or redeem delegations (ERC-7710)
+- You want to request Advanced Permissions via MetaMask extension (ERC-7715)
+- You want to build automated backend services (DCA bots, keeper services) using delegations
+- You want to implement session accounts for AI agents or automated trading
+- You want to set up parallel user operations with nonce keys
+
+## Installation
+
+```bash
+npm install @metamask/smart-accounts-kit permissionless
+```
+
+## Which smart account type to use
+
+| Name | Usage |
+|------|-------|
+| Hybrid | A flexible account with EOA, wallet client, and passkey (WebAuthn) signers. The most flexible option for standard dApp users. |
+| MultiSig | Requires multiple signers to meet a threshold before transactions execute. Best for treasury, DAO, or shared custody use cases. |
+| Stateless7702 | Upgrades an existing EOA to a smart account using EIP-7702 while keeping the same address. Best for users with existing embedded EOAs. |
+
+If the user hasn't specified which implementation they need, present the options.
+
+## Delegations vs Advanced Permissions
+
+| Name | Usage |
+|------|-------|
+| Delegations (ERC-7710) | You create, sign, and manage delegations programmatically. The delegator is a smart account you control. You handle the full lifecycle: creation, signing, storage, and redemption. |
+| Advanced Permissions (ERC-7715) | You request permissions from a MetaMask user through a human-readable UI in the extension. MetaMask creates and enforces the delegations internally. The user can review and adjust parameters before approving. |
+
+Advanced Permissions use delegations under the hood — ERC-7715 creates ERC-7710 delegations internally. If the user hasn't specified which to use, present the options.
+
+## API references
+
+| Use case | Reference | Workflows |
+|----------|-----------|-----------|
+| Create a smart account | [toMetaMaskSmartAccount](./references/smart-accounts.md) | [Create hybrid account](./workflows/create-hybrid-account.md), [Create multisig account](./workflows/create-multisig-account.md), [Create 7702 account](./workflows/create-7702-account.md) |
+| Create a delegation | [createDelegation](./references/delegations.md) | [Create delegation](./workflows/create-delegation.md), [Create redelegation](./workflows/create-redelegation.md) |
+| Request ERC-7715 permissions | [requestExecutionPermissions](./references/advanced-permissions.md) | [Request permissions](./workflows/request-permissions.md), [Redeem — smart account](./workflows/redeem-permissions-smart-account.md), [Redeem — EOA](./workflows/redeem-permissions-eoa.md) |
+
+## Workflows
+
+| Use case | Workflow |
+|----------|----------|
+| Create a Hybrid smart account | [Create hybrid account](./workflows/create-hybrid-account.md) |
+| Create a MultiSig smart account | [Create multisig account](./workflows/create-multisig-account.md) |
+| Create a Stateless7702 smart account | [Create 7702 account](./workflows/create-7702-account.md) |
+| Create and sign a delegation | [Create delegation](./workflows/create-delegation.md) |
+| Create a delegation chain (redelegation) | [Create redelegation](./workflows/create-redelegation.md) |
+| Redeem a delegation when the delegate is a smart account | [Redeem delegation — smart account](./workflows/redeem-delegation-smart-account.md) |
+| Redeem a delegation when the delegate is an EOA | [Redeem delegation — EOA](./workflows/redeem-delegation-eoa.md) |
+| Request ERC-7715 Advanced Permissions | [Request permissions](./workflows/request-permissions.md) |
+| Redelegate an ERC-7715 permission context | [Create redelegation for permissions](./workflows/create-redelegation-permissions.md) |
+| Redeem ERC-7715 permissions when the session account is a smart account | [Redeem permissions — smart account](./workflows/redeem-permissions-smart-account.md) |
+| Redeem ERC-7715 permissions when the session account is an EOA | [Redeem permissions — EOA](./workflows/redeem-permissions-eoa.md) |
+
+## Important notes
+
+- Always use caveats — never create unrestricted delegations.
+- Deploy the delegator first — the account must be deployed before redeeming delegations.
+- Function call scope defaults to no native token — use `valueLte` to allow it.
+- Caveats are cumulative in delegation chains — restrictions stack.
+- ERC-7715 requires MetaMask Flask 13.5.0+ or MetaMask stable 13.23.0+, and the user must have a smart account.
+- Always check that the project builds successfully after making changes.
+- Smart Accounts Kit version: 1.6.0 | Delegation Framework: 1.3.0
+
+## Resources
+
+- NPM: `@metamask/smart-accounts-kit`
+- Contract deployments: [Delegation Framework deployments](https://github.com/MetaMask/delegation-framework/blob/main/documents/Deployments.md)
+- Docs: https://docs.metamask.io/smart-accounts-kit
+- MetaMask Flask: https://metamask.io/flask

skills/smart-accounts-kit/references/advanced-permissions.md

@@ -0,0 +1,69 @@
+---
+name: Advanced Permissions
+description: API reference for requesting ERC-7715 Advanced Permissions from MetaMask extension
+---
+
+# Advanced Permissions
+
+## When to use
+
+- You want to request fine-grained permissions from MetaMask with a human-readable UI.
+- You want periodic or streaming spending allowances without per-transaction approvals.
+- You want to build dApps with background or automated transaction execution.
+
+## API reference
+
+### `requestExecutionPermissions` parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `chainId` | `number` | Yes | The chain ID on which the permission is being requested |
+| `to` | `Address` | Yes | The account to which the permission will be assigned |
+| `permission` | `SupportedPermissionParams` | Yes | The permission type being requested, with `isAdjustmentAllowed` flag |
+| `expiry` | `number` | Yes | The timestamp (in seconds) by which the permission must expire |
+| `from` | `Address` | No | The wallet address from which permission is requested |
+
+For more details, see the [requestExecutionPermissions reference](https://docs.metamask.io/smart-accounts-kit/reference/advanced-permissions/wallet-client.md).
+
+### Supported permission types
+
+| Type | When to use |
+|------|-------------|
+| `erc20-token-allowance` | You want a fixed ERC-20 transfer limit that depletes until the total reaches the allowance |
+| `erc20-token-periodic` | You want a per-period ERC-20 limit that resets at the start of each new period |
+| `erc20-token-stream` | You want a linear streaming ERC-20 limit that accrues over time |
+| `native-token-allowance` | You want a fixed native token transfer limit that depletes until the total reaches the allowance |
+| `native-token-periodic` | You want a per-period native token limit that resets at the start of each new period |
+| `native-token-stream` | You want a linear streaming native token limit that accrues over time |
+| `token-approval-revocation` | You want to revoke existing token approvals (ERC-20, ERC-721, Permit2) on behalf of the user |
+
+The token allowance, native token allowance, periodic, and stream permission types accept optional `startTime`, `justification`, and `isAdjustmentAllowed` parameters. The `token-approval-revocation` type only accepts `justification` and `isAdjustmentAllowed`. For full parameter details, see the [permissions reference](https://docs.metamask.io/smart-accounts-kit/reference/advanced-permissions/permissions.md).
+
+### Response structure
+
+```typescript
+{
+  context: Hex,                // Encoded permission context for redemption
+  delegationManager: Address,  // Delegation Manager address
+  chainId: number,
+  from: Address,               // Granting address
+  to: Hex,                     // Receiving address
+  permission: PermissionTypes,
+  dependencies: { factory: Address, factoryData: Hex }[],
+}
+```
+
+## Important rules
+
+- You need MetaMask Flask 13.5.0+ or MetaMask stable 13.23.0+.
+- The user must have a smart account — ERC-7715 creates ERC-7710 delegations under the hood.
+- Place `isAdjustmentAllowed` inside the `permission` object. It's always recommended.
+- Handle denial gracefully — provide a manual transaction fallback.
+- `erc20-token-revocation` is deprecated — use `token-approval-revocation` instead.
+
+## Workflows
+
+- [Request permissions](../workflows/request-permissions.md) — request ERC-7715 permissions from MetaMask
+- [Create redelegation for permissions](../workflows/create-redelegation-permissions.md) — redelegate a permission context to another account
+- [Redeem permissions — smart account](../workflows/redeem-permissions-smart-account.md) — redeem when the session account is a smart account
+- [Redeem permissions — EOA](../workflows/redeem-permissions-eoa.md) — redeem when the session account is an EOA

skills/smart-accounts-kit/references/delegations.md

@@ -0,0 +1,104 @@
+---
+name: Delegations
+description: API reference for creating delegations with scopes and caveat enforcers — ERC-7710 delegation framework
+---
+
+# Delegations
+
+## When to use
+
+- You want to grant permissions from one account to another (delegator to delegate).
+- You want to set spending limits (ERC-20, native token, NFT).
+- You want to restrict function calls to specific contracts or methods.
+- You want to add time limits, call limits, or other restrictions via caveats.
+- You want to create delegation chains (redelegation).
+
+## API reference
+
+### `createDelegation` parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `from` | `Hex` | Yes | The address granting the delegation |
+| `to` | `Hex` | Yes | The address receiving the delegation |
+| `scope` | `ScopeConfig` | Yes | Defines the initial authority of the delegation |
+| `environment` | `SmartAccountsEnvironment` | Yes | Contract addresses for framework interactions |
+| `caveats` | `Caveats` | No | Caveats that further refine the authority granted by the scope |
+| `parentDelegation` | `Delegation \| Hex` | No | Parent delegation for creating a chain (mutually exclusive with `parentPermissionContext`) |
+| `parentPermissionContext` | `PermissionContext` | No | Parent chain as hex or decoded values, leaf first (mutually exclusive with `parentDelegation`) |
+| `salt` | `Hex` | No | Salt for generating the delegation hash to prevent collisions |
+
+For more details, see the [delegation reference](https://docs.metamask.io/smart-accounts-kit/reference/delegation.md).
+
+### Scope types
+
+Use the `ScopeType` enum for type-safe scope configuration:
+
+| ScopeType | When to use |
+|-----------|-------------|
+| `Erc20TransferAmount` | You want to set a fixed cumulative ERC-20 transfer limit |
+| `Erc20PeriodTransfer` | You want a per-period ERC-20 limit that resets at the start of each new period |
+| `Erc20Streaming` | You want a linear streaming ERC-20 limit that accrues over time |
+| `NativeTokenTransferAmount` | You want to set a fixed cumulative native token transfer limit |
+| `NativeTokenPeriodTransfer` | You want a per-period native token limit that resets at the start of each new period |
+| `NativeTokenStreaming` | You want a linear streaming native token limit that accrues over time |
+| `Erc721Transfer` | You want to restrict the delegation to a specific NFT transfer |
+| `FunctionCall` | You want to restrict the delegation to specific methods, addresses, or calldata |
+| `OwnershipTransfer` | You want to restrict the delegation to ownership transfer calls only |
+
+For full scope parameters, see the [delegation scopes guide](https://docs.metamask.io/smart-accounts-kit/guides/delegation/use-delegation-scopes.md).
+
+### Caveat types
+
+| Type | When to use |
+|------|-------------|
+| `allowedTargets` | You want to restrict which contract addresses the delegate can call |
+| `allowedMethods` | You want to restrict which methods the delegate can call |
+| `allowedCalldata` | You want to validate specific calldata at a byte offset |
+| `exactCalldata` | You want to require an exact calldata match |
+| `exactCalldataBatch` | You want to require an exact calldata match for a batch of executions |
+| `exactExecution` | You want to require an exact match on target, value, and calldata |
+| `exactExecutionBatch` | You want to require an exact match for a batch of executions |
+| `valueLte` | You want to cap the native token value per call |
+| `erc20TransferAmount` | You want to set a max cumulative ERC-20 transfer amount |
+| `erc20BalanceChange` | You want to validate that an ERC-20 balance changes as expected |
+| `erc20PeriodTransfer` | You want a per-period ERC-20 limit that resets each period |
+| `erc20Streaming` | You want a linear streaming ERC-20 limit that accrues over time |
+| `erc721Transfer` | You want to restrict the delegation to a specific NFT transfer |
+| `erc721BalanceChange` | You want to validate that an ERC-721 balance changes as expected |
+| `erc1155BalanceChange` | You want to validate that an ERC-1155 balance changes as expected |
+| `nativeTokenPeriodTransfer` | You want a per-period native token limit that resets each period |
+| `nativeTokenStreaming` | You want a linear streaming native token limit that accrues over time |
+| `nativeBalanceChange` | You want to validate that a native token balance changes as expected |
+| `nativeTokenPayment` | You want to require the redeemer to pay a fee to redeem |
+| `timestamp` | You want to restrict redemption to a specific time window |
+| `blockNumber` | You want to restrict redemption to a specific block range |
+| `limitedCalls` | You want to limit how many times the delegation can be redeemed |
+| `redeemer` | You want to restrict which addresses can redeem the delegation |
+| `id` | You want a one-time delegation identified by a unique ID |
+| `nonce` | You want to enable bulk revocation of delegations sharing the same nonce |
+| `deployed` | You want to auto-deploy a contract before the delegation executes |
+| `ownershipTransfer` | You want to restrict the delegation to ownership transfer calls only |
+| `multiTokenPeriod` | You want to set per-period limits across multiple tokens at once |
+| `specificActionERC20TransferBatch` | You want to combine a specific action with an ERC-20 transfer in a batch |
+| `argsEqualityCheck` | You want to validate that function arguments match a specific value |
+
+For full caveat parameters, see the [caveats reference](https://docs.metamask.io/smart-accounts-kit/reference/delegation/caveats.md).
+
+## Important rules
+
+- The delegator must always be a MetaMask smart account created with `toMetaMaskSmartAccount`.
+- You must deploy the delegator before redeeming delegations — the DelegationManager reverts with `0xb9f0f171` for counterfactual accounts.
+- Always use caveats — without them, delegations have infinite authority.
+- Function call scope defaults to no native token — use `valueLte` to allow it.
+- Caveats are cumulative in chains — restrictions stack, and a delegate can only redelegate with equal or lesser authority.
+- Caveat order matters — place state-changing caveats (payment) before balance checks.
+- Use the `ScopeType` enum for type-safe scope configuration.
+
+## Workflows
+
+- [Create delegation](../workflows/create-delegation.md) — create, sign, and store a delegation
+- [Create redelegation](../workflows/create-redelegation.md) — delegation chains with attenuated authority
+- [Redeem delegation — smart account](../workflows/redeem-delegation-smart-account.md) — redeem when the delegate is a smart account
+- [Redeem delegation — EOA](../workflows/redeem-delegation-eoa.md) — redeem when the delegate is an EOA
+