feat: migrate to domains/ layout, add multi-source install tooling

.gitattributes

@@ -0,0 +1,7 @@
+# Force LF for shell scripts so `tools/*` work in WSL / Git Bash on Windows.
+# Without this, Windows clones with core.autocrlf=true rewrite to CRLF and bash
+# fails with `$'\r': command not found` and `set: invalid option`.
+tools/install   text eol=lf
+tools/sync      text eol=lf
+tools/deploy    text eol=lf
+*.sh            text eol=lf

.gitignore

@@ -33,3 +33,6 @@ logs/
 .env.local
 .env.*.local
 secrets.json
+
+# Maintainer-local config for tools/deploy
+.targets.local

.targets.local.example

@@ -0,0 +1,17 @@
+# tools/deploy reads this file (after you copy it to `.targets.local`).
+# Format: <consumer-repo-name>=<path-or-glob>
+#
+# - LHS is the value passed to `tools/install --repo`. Must match a name
+#   the install CLI knows (e.g. metamask-extension, metamask-mobile).
+# - RHS is a path to the consumer checkout. Globs are expanded, so one
+#   line can hit many worktrees at once.
+# - $HOME and ~ are expanded.
+# - Lines starting with `#` are ignored. Repeated LHS is fine.
+
+# Worktree fan-out (one line, matches all checkouts of that repo):
+metamask-extension=$HOME/dev/metamask/metamask-extension*
+metamask-mobile=$HOME/dev/metamask/metamask-mobile*
+
+# Or list individual paths explicitly (e.g. only one worktree, or non-default name):
+# metamask-extension=$HOME/dev/metamask/metamask-extension-4
+# metamask-mobile=$HOME/work/mobile

README.md

@@ -1,79 +1,270 @@
-# MetaMask OpenClaw Skills
+# MetaMask/skills
 
-A curated library of [OpenClaw](https://github.com/BankrBot/openclaw-skills) skills approved and recommended by MetaMask developers. This repository serves as a trusted collection of AI agent skills for building, testing, and interacting with MetaMask and the broader Ethereum ecosystem.
+Agent skills, rules, and domain knowledge for the MetaMask ecosystem.
 
-## What are OpenClaw Skills?
+Two audiences share this repo:
 
-OpenClaw skills are modular instruction sets that enable AI coding agents to perform specialized tasks. Each skill contains a `SKILL.md` file with structured guidance that AI agents can follow to accomplish specific goals—from deploying smart contracts to interacting with DeFi protocols.
+1. **dApp / Web3 developers** — skills under `domains/web3-tools/` teach AI
+   agents how to use MetaMask developer libraries (`gator-cli`,
+   `smart-accounts-kit`, OpenCode plugin, etc.). Drop them into your
+   editor/agent and it will operate the tooling correctly.
+2. **MetaMask product engineers** — skills under `domains/perps/`,
+   `domains/testing/`, `domains/pr-workflow/`, etc. carry the conventions
+   and review heuristics for `metamask-extension` and `metamask-mobile`.
+   These install into consumer repos via a small CLI.
 
-## Repository Structure
+Single source of truth, multi-operator output (Claude Code, Cursor,
+Codex/OpenAI), public canonical, private overlay optional.
 
+> **Private overlay:** internal-only skills (Consensys-wide tooling,
+> in-progress experiments, non-public products) live in a separate
+> private repo, [`Consensys/skills`](https://github.com/Consensys/skills).
+> Engineers with access can layer those skills on top of the public set.
+> See [Federation](#federation-public--private).
+
+## Quickstart
+
+### For dApp / Web3 developers (use a single skill)
+
+Point your agent at this repo and load the skill that matches your
+tooling. For example, to use the `gator-cli` skill in Claude Code:
+
+```bash
+# One-time clone:
+git clone https://github.com/MetaMask/skills ~/dev/metamask/skills
+
+# Copy or symlink the skill you want into your project (or ~/.claude/skills):
+cp -r ~/dev/metamask/skills/domains/web3-tools/skills/gator-cli/* \
+     ~/.claude/skills/gator-cli/
+```
+
+Or use the installer to drop all `web3-tools/` skills at once:
+
+```bash
+~/dev/metamask/skills/tools/install \
+  --repo metamask-extension --target . --domain web3-tools
 ```
-metamask-openclaw-skills/
-├── provider-name/
-│   ├── skill-name/
-│   │   ├── SKILL.md          # Main skill definition (required)
-│   │   ├── references/       # Supporting documentation (optional)
-│   │   └── scripts/          # Helper scripts (optional)
-│   └── another-skill/
-│       └── SKILL.md
-├── CONTRIBUTING.md
-└── README.md
+
+### For engineers in `metamask-extension` / `metamask-mobile`
+
+```bash
+# One time:
+git clone https://github.com/MetaMask/skills ~/dev/metamask/skills
+export METAMASK_SKILLS_DIR=~/dev/metamask/skills
+
+# Then, from inside the consumer repo:
+yarn skills
 ```
 
-## Available Skills
+`yarn skills` runs `tools/sync`, which pulls the latest skills and writes
+them into `.claude/skills/`, `.cursor/rules/`, and `.agents/skills/`.
+
+### For cloud agents (Cursor cloud, Codex cloud, etc.)
 
-| Provider | Skill | Description |
-|----------|-------|-------------|
-| *Coming soon* | — | Skills will be added via community PRs |
+No SSH key, no env var — one curl pipe to bash inside the consumer repo:
 
-## Installation
+```bash
+curl -fsSL https://raw.githubusercontent.com/MetaMask/skills/main/tools/bootstrap | \
+  bash -s -- --repo metamask-extension
+```
+
+The bootstrap script clones this repo into a cache dir under
+`$HOME/.cache/metamask-skills` and runs the installer against the current
+directory.
 
-Point your AI agent to this repository URL:
+## Repo structure
 
 ```
-https://github.com/MetaMask/openclaw-skills
+domains/<area>/
+  skills/<skill-name>/
+    skill.md                    # base skill
+    references/                 # optional supporting docs
+    scripts/                    # optional helper scripts
+    repos/<consuming-repo>.md   # optional repo-specific overlay
+  knowledge/                    # optional shared domain reference
+tools/
+  install      # core writer (mms- prefix, multi-operator output)
+  sync         # Flow 2: `yarn skills` wrapper for engineers
+  deploy       # Flow 1: maintainer push to multiple targets
+  bootstrap    # zero-config installer for cloud agents
+.targets.local.example          # template for maintainer config
 ```
 
-The agent will present available skills for installation.
+## Domains today
 
-## Adding a New Skill
+| Domain         | Audience          | Examples                                    |
+| -------------- | ----------------- | ------------------------------------------- |
+| `web3-tools`   | dApp builders     | `gator-cli`, `smart-accounts-kit`, `oh-my-opencode` |
+| `coding`       | MM product eng    | Coding guidelines, controller patterns       |
+| `general`      | All agents        | `codex`, `gemini` CLI usage guides           |
+| `performance`  | MM product eng    | React rendering, hooks, state perf          |
+| `perps`        | MM product eng    | Perps feature dev + review                  |
+| `pr-workflow`  | MM product eng    | PR title, description, changelog            |
+| `swaps`        | MM product eng    | Non-EVM swap integration                    |
+| `testing`      | MM product eng    | E2E, unit, visual, perf testing             |
+| `ui`           | MM product eng    | Component development                       |
 
-We welcome contributions from the community! To add a new skill:
+## Two distribution flows
 
-1. **Fork this repository** and create a new branch
-2. **Create your provider directory** (if it doesn't exist):
-   ```bash
-   mkdir -p your-provider-name/your-skill-name/
-   ```
-3. **Add the required `SKILL.md`** following our [skill template](.github/SKILL_TEMPLATE.md)
-4. **Add optional supporting files**:
-   - `references/` — Additional documentation
-   - `scripts/` — Helper scripts
-5. **Submit a Pull Request** with a clear description
+### Flow 1 — Push (maintainer)
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+From inside `MetaMask/skills`, push the current state to one or more
+consumer checkouts.
 
-## Skill Guidelines
+**One target:**
 
-Skills included in this repository should:
+```bash
+tools/install --repo metamask-extension --target ~/dev/metamask/metamask-extension
+```
 
-- ✅ Be relevant to MetaMask users and Ethereum developers
-- ✅ Follow security best practices
-- ✅ Include clear documentation and examples
-- ✅ Be tested before submission
-- ✅ Not include malicious code or instructions
+**All configured targets:**
 
-## Security
+```bash
+cp .targets.local.example .targets.local   # one-time
+# edit paths
+tools/deploy
+tools/deploy --domain perps --dry-run      # forwarded to install
+```
+
+`.targets.local` is gitignored.
+
+### Flow 2 — Pull (engineer)
+
+From inside a consumer repo:
+
+```bash
+yarn skills                                          # interactive prompt
+SKILLS_DOMAINS=perps,testing yarn skills             # non-interactive
+METAMASK_SKILLS_DIR=/some/path yarn skills           # override location
+```
+
+`yarn skills` calls `tools/sync`, which pulls the source repos, then
+execs `tools/install` with each as `--source`.
+
+If neither env var is set, the script prints setup instructions and exits.
+**No silent auto-clone** — engineers see the path they're opting into.
+
+## Manual install (the primitive)
+
+Both flows ultimately invoke `tools/install`:
+
+```bash
+tools/install \
+  --repo metamask-mobile \
+  --target ~/dev/metamask/metamask-mobile \
+  --domain perps \
+  --dry-run
+```
+
+### Flags
+
+| Flag             | Default  | Purpose                                                                          |
+| ---------------- | -------- | -------------------------------------------------------------------------------- |
+| `--target`       | required | Path to consuming repo                                                           |
+| `--repo`         | auto     | Consuming repo name. Auto-detected from `<target>/package.json` `name` (fallback: target dirname). |
+| `--source`       | this repo | Skill source dir (repeatable, ordered; later overrides earlier on name collision) |
+| `--domain`       | all      | Comma-separated domain filter. Default installs **all** domains; pass to opt out. |
+| `--maturity`     | `stable` | Min maturity: `experimental`, `stable`, `deprecated`                             |
+| `--include-user` | off      | Also install `scope: user` skills (writes to `$HOME` — outside the target repo). Default skips them with a warning. |
+| `--dry-run`      | off      | Preview without writing                                                          |
+
+**Install-all default.** Skills install for every domain by default. Engineers
+opt out per-machine by editing `.skills.local` (`SKILLS_DOMAINS=perps,testing`)
+or by running `yarn skills --select` for an interactive picker. New domains
+land automatically on the next sync — that's by design so new tooling is
+discoverable.
 
-If you discover a security vulnerability in any skill, please report it responsibly. Do not open a public issue. Instead, follow MetaMask's [security policy](https://github.com/MetaMask/metamask-extension/security/policy).
+**User-scope skills (`scope: user` in frontmatter).** Some skills target the
+engineer's home dir (`$HOME/.claude/skills`, `$HOME/.codex/skills`) instead
+of the target repo. They are **never auto-installed** — installer lists them
+in a final warning. Run with `--include-user` to install manually.
+
+### Output
+
+Per consuming repo, the CLI writes:
+
+- `.claude/skills/mms-<name>/SKILL.md` — Claude Code, OpenCode
+- `.cursor/rules/mms-<name>/RULE.md` — Cursor
+- `.agents/skills/mms-<name>/SKILL.md` + `agents/openai.yaml` — Codex, OpenCode
+
+All output names are prefixed `mms-` (managed metamask skill). Source
+frontmatter `name:` stays unprefixed; the prefix is applied at install time.
+
+Each output file carries a `<!-- DO NOT EDIT -->` banner. Synced content
+is additive and intended to be `.gitignore`'d in consuming repos.
+
+## Federation (public + private)
+
+When both env vars are set, `tools/sync` walks both sources and the
+private overlay overrides the public skill on name conflict. This matches
+the "most-local wins" priority below.
+
+```bash
+export METAMASK_SKILLS_DIR=~/dev/metamask/skills        # public, this repo
+export CONSENSYS_SKILLS_DIR=~/dev/Consensys/skills      # private overlay
+yarn skills
+```
+
+Engineers without access to the private repo simply don't set
+`CONSENSYS_SKILLS_DIR` — the public set installs cleanly on its own.
+
+## Authoring a skill
+
+```
+domains/<area>/
+  skills/<skill-name>/
+    skill.md
+    references/                   # optional supporting docs
+    scripts/                      # optional helper scripts
+    repos/metamask-extension.md   # optional repo overlay
+    repos/metamask-mobile.md      # optional repo overlay
+```
+
+### `skill.md` frontmatter
+
+```yaml
+---
+name: <slash-command-name>
+description: <≤1,536 chars including when_to_use cues>
+maturity: stable          # experimental | stable | deprecated (default stable)
+---
+```
+
+Extra metadata blocks (e.g. OpenClaw-style `metadata:` with emoji and
+homepage) are preserved through install — only `name`, `description`,
+`maturity`, `mandatory`, and `scope` are read by the CLI.
+
+### Overlay frontmatter
+
+```yaml
+---
+repo: metamask-extension
+parent: <skill-name>
+---
+```
+
+Overlays merge into the base body at install time. Skills with a `repos/`
+subdir but no overlay matching `--repo` are skipped for that target.
+Skills with no `repos/` subdir at all install for any target.
+
+## Multi-operator priority
+
+```
+Enterprise > User (~/.claude/skills/) > Project (.claude/skills/)
+```
+
+Most-local wins on name conflict. The `mms-` prefix on output names
+prevents collision with personal skills.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT — see [LICENSE](LICENSE).
 
-## Links
+## Security
 
-- [MetaMask Extension](https://github.com/MetaMask/metamask-extension)
-- [MetaMask Developer Docs](https://docs.metamask.io/)
-- [OpenClaw Skills (Original)](https://github.com/BankrBot/openclaw-skills)
+See [SECURITY.md](SECURITY.md) for how to report issues with skills or
+the installer.

SECURITY.md

@@ -0,0 +1,25 @@
+# Security policy
+
+This repo contains agent instructions and prompt templates only — no
+runtime code that ships in MetaMask products. Reports about the **content**
+of a skill (e.g., guidance that could lead to insecure code) are welcome.
+
+For vulnerabilities in shipped MetaMask products, follow the disclosure
+flow at https://metamask.io/security/.
+
+## Reporting an issue with a skill
+
+- Open a public issue on https://github.com/MetaMask/skills/issues if the
+  problem is non-sensitive (typo, outdated reference, broken link).
+- Email `[email protected]` if the skill instructs an agent to perform
+  an action with safety implications (e.g., bypassing review controls,
+  leaking secrets, weakening test coverage), so a maintainer can patch
+  before discussion is public.
+
+## Out of scope
+
+- The installer scripts (`tools/install`, `tools/sync`, `tools/deploy`,
+  `tools/bootstrap`) run locally on engineer machines or cloud agents and
+  do not handle credentials. Treat bugs as ordinary issues.
+- Skills are advisory — agents and reviewers are expected to apply
+  judgment. A skill recommendation is not a security guarantee.