Description

Follow-up to #29853. Switches yarn skills to the new public MetaMask/skills repo, with the private Consensys/skills repo available as an optional overlay for internal-only material. Adds a postinstall hook so engineers get an auto-updated skill set on every yarn install — no manual yarn skills needed.

Why public

• Cloud agents (Cursor cloud, Codex cloud, Claude.ai web) can't git clone a private repo or set engineer-managed env vars. The public repo solves this with a one-liner curl bootstrap (no SSH, no auth).
• New engineers don't need Consensys SSO to start using skills — the public set installs cleanly on its own.
• Out-of-the-box auto-sync via postinstall (Ramon's ask in #engineering-mobile).

Engineer experience (zero-config)

yarn install   # postinstall clones MetaMask/skills into .skills-cache/ and installs
yarn skills    # auto-detects the cache, no env var or shell rc edit needed

Override only if you keep a separate clone:

export METAMASK_SKILLS_DIR=~/dev/metamask/skills
export CONSENSYS_SKILLS_DIR=~/dev/Consensys/skills   # optional private overlay

Changes

• scripts/skills-sync.mts — multi-source aware wrapper (was bash, ported to node .mts for cross-platform consistency). Resolution order: METAMASK_SKILLS_DIR → CONSENSYS_SKILLS_DIR → auto-fallback to .skills-cache/metamask-skills. When the cache is used, injects METAMASK_SKILLS_DIR=<cache> so the bash sync underneath sees the source.
• scripts/skills-postinstall.mts (new) — auto-clones MetaMask/skills into .skills-cache/metamask-skills and runs the installer on every yarn install. Layered with CONSENSYS_SKILLS_DIR when set. Best-effort: skipped on CI, on SKILLS_SKIP_POSTINSTALL=1, or when offline. Opt back in on CI with SKILLS_FORCE_POSTINSTALL=1.
• .gitignore — adds .skills-cache/, updates comments to reference public canonical.
• package.json — adds postinstall hook + lavamoat "$root$": true allowScripts entry; skills script uses tsx scripts/skills-sync.mts (node 20 has no native TS).
• .skills.local.example — documents new zero-config default + optional env-var override.

Companion PRs

• MetaMask/skills (merged) — public source of truth, install CLI, multi-source sync, cloud-agent bootstrap.
• Consensys/skills#9 — private overlay only; repo retained for future internal material.
• MetaMask/metamask-extension#42488 — parallel extension migration.
• MetaMask/decisions#162 — ADR amendment.

Out of scope

• TS rewrite of CLI.
• Personal-skills tooling.

Changelog

CHANGELOG entry: null

Related issues

Fixes:

Manual testing steps

Feature: zero-config yarn skills sync

  Scenario: fresh clone, no env vars
    Given the engineer cloned this branch and has no METAMASK_SKILLS_DIR set
    When they run `yarn install`
    Then `.skills-cache/metamask-skills/` is populated from MetaMask/skills
    And skills are installed under `.claude/`, `.cursor/`, `.agents/`
    And `git status --short` reports a clean working tree
    When they later run `yarn skills`
    Then the wrapper auto-detects the cache and re-syncs without any env var

  Scenario: engineer with explicit clone
    Given METAMASK_SKILLS_DIR points at a separate clone outside the repo
    When the engineer runs `yarn skills`
    Then the explicit clone is used in preference to the cache

  Scenario: federation with private overlay
    Given METAMASK_SKILLS_DIR and CONSENSYS_SKILLS_DIR both point at valid clones
    When the engineer runs `yarn skills`
    Then skills from both sources install
    And on name collision the Consensys (private) version wins

  Scenario: CI install skips postinstall by default
    Given CI=1 is set
    When the engineer runs `yarn install`
    Then skills-postinstall.mts exits immediately without writing anything

  Scenario: CI install opts back in
    Given CI=1 and SKILLS_FORCE_POSTINSTALL=1 are set
    When the engineer runs `yarn install`
    Then skills-postinstall.mts clones the cache and runs the install

  Scenario: opt out per machine
    Given SKILLS_SKIP_POSTINSTALL=1 is set
    When the engineer runs `yarn install`
    Then skills-postinstall.mts exits immediately

  Scenario: Windows engineer without WSL/Git Bash
    Given the engineer runs the wrapper on Windows PowerShell
    When they run `yarn skills` or `yarn install`
    Then the node wrappers execute without requiring bash on PATH at the wrapper layer

Screenshots/Recordings

No UI change — agent tooling and repo wiring only.

Before

N/A

After

N/A

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Performance checks (if applicable)

• I've tested on Android
• I've tested with a power user scenario
• I've instrumented key operations with Sentry traces for production performance metrics

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.