chore: centralize agent skills via public MetaMask/skills (+ private Consensys overlay)#42488
Merged
Conversation
Per ADR #57. Removes committed skills/rules now provided by the centralized Consensys/skills repo, ignores agent dirs so engineers can mix synced (`mms-*`) and personal skills locally without git noise. Engineer entrypoint: `yarn skills` (calls Consensys/skills/tools/sync, which pulls latest, optionally prompts for domains, then installs). Set CONSENSYS_SKILLS_DIR or accept default (~/dev/Consensys/skills). Removed (covered by mms- inject set): - 12 .cursor/rules/ (coding-guidelines, controller-guidelines, e2e-testing-guidelines, extension-flakiness-patterns, front-end-performance-{hooks-effects,react-compiler, rendering,state-management}, pull-request-guidelines, test-i18n-usage, ui-development-guidelines, unit-testing-guidelines) - 3 .claude/skills/ (ab-testing-implementation, add-non-evm-swaps-bridge-network, metamask-visual-testing) + 1 symlink (creating-e2e-tests) - 1 .claude/commands/add-non-evm-swaps-bridge-network.md - 2 .cursor/skills/ (add-non-evm-swaps-bridge-network, creating-e2e-tests) - 2 .agents/skills/ (ab-testing-implementation, add-non-evm-swaps-bridge-network) Companion PRs: - Consensys/skills#2 (source of truth + CLI) - MetaMask/decisions#162 (ADR amendment) - MetaMask/metamask-mobile (parallel migration)
Per review feedback: don't default the source location to ~/dev/Consensys/skills. If the env var is unset, fail fast with setup instructions. - New: development/skills-sync.sh — yarn skills entrypoint, validates env and the source path before delegating to Consensys/skills/tools/sync. - Updated: package.json `skills` script now calls the wrapper. Engineers see clear instructions instead of obscure shell errors when the source repo isn't configured.
Contributor
|
CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes. |
10 tasks
…-skills # Conflicts: # package.json
…ore .skills.local Match the equivalent block in metamask-mobile#29853: - ignore .skills.local (per-engineer domain selection persisted by yarn skills) - explicit !.cursor/BUGBOT.md carve-out so IDE/bugbot config stays tracked - comment clarifies that synced agent dirs are never tracked, IDE config stays
Contributor
Builds ready [c6b6153]
⚡ Performance Benchmarks (Total: 🟢 15 pass · 🟡 10 warn · 🔴 0 fail)
Bundle size diffs [🚨 Warning! Bundle size has increased!]
|
Contributor
Builds ready [6b248e7]
⚡ Performance Benchmarks (Total: 🟢 13 pass · 🟡 11 warn · 🔴 0 fail)
Bundle size diffs [🚨 Warning! Bundle size has increased!]
|
aganglada
previously approved these changes
May 20, 2026
Contributor
Builds ready [4d1cfa4]
⚡ Performance Benchmarks (Total: 🟢 12 pass · 🟡 13 warn · 🔴 0 fail)
Bundle size diffs [🚨 Warning! Bundle size has increased!]
|
gauthierpetetin
previously approved these changes
May 20, 2026
itsyoboieltr
previously approved these changes
May 20, 2026
Contributor
|
@abretonc7s, I don't want to block the merge of this PR in case it's urgent, so this is more a question for a potential follow-up PR:
|
MajorLift
reviewed
May 20, 2026
| with: | ||
| max-lines: '1000' | ||
| ignore-patterns: '(\.lock|\.snap|lavamoat\/.*policy\.json)$' | ||
| ignore-patterns: '(\.lock|\.snap|lavamoat\/.*policy\.json)$|\.(agents|claude|cursor)\/' |
Contributor
There was a problem hiding this comment.
Do we expect anything to be committed in these paths despite the corresponding gitignore entries? Even if so, shouldn't they count towards max line count as review targets?
Suggested change
| ignore-patterns: '(\.lock|\.snap|lavamoat\/.*policy\.json)$|\.(agents|claude|cursor)\/' | |
| ignore-patterns: '(\.lock|\.snap|lavamoat\/.*policy\.json)$' |
Contributor
Author
There was a problem hiding this comment.
Addressed in 521e815 by narrowing the PR line-count ignore pattern to lock files, snapshots, and LavaMoat policy files only.
Contributor
Author
There was a problem hiding this comment.
MajorLift
reviewed
May 20, 2026
Contributor
Builds ready [7547ca4]
⚡ Performance Benchmarks (Total: 🟢 12 pass · 🟡 12 warn · 🔴 0 fail)
Bundle size diffs [🚨 Warning! Bundle size has increased!]
|
geositta
reviewed
May 20, 2026
Contributor
There was a problem hiding this comment.
Requesting changes because the new automatic setup path does not match the behavior documented for developers. postinstall uses Bash 3.2 on macOS even though the shared installer requires Bash 4 syntax, and it bypasses the .skills.local domain selection that yarn skills honors. The path override example also needs to match what the TypeScript wrapper can resolve.
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 872deeb. Configure here.
Contributor
Builds ready [872deeb]
⚡ Performance Benchmarks (Total: 🟢 14 pass · 🟡 10 warn · 🔴 0 fail)
Bundle size diffs [🚨 Warning! Bundle size has increased!]
|
geositta
reviewed
May 21, 2026
geositta
left a comment
Contributor
There was a problem hiding this comment.
The wrapper issues from the previous pass are resolved.
The remaining blockers are in AGENTS.md. It still says yarn install syncs generated agent paths, and it still points Claude users at a command file that this PR deletes and the public skills installer does not restore. Both issues leave agent guidance pointing at behavior or files that will not exist after this migration.
Contributor
Builds ready [176813e] [reused from 9ced553]
⚡ Performance Benchmarks (Total: 🟢 14 pass · 🟡 11 warn · 🔴 0 fail)
Bundle size diffs [🚨 Warning! Bundle size has increased!]
|
geositta
previously approved these changes
May 21, 2026
|
Contributor
Builds ready [69d1b60]
⚡ Performance Benchmarks (Total: 🟢 12 pass · 🟡 13 warn · 🔴 0 fail)
Bundle size diffs [🚨 Warning! Bundle size has increased!]
|
gauthierpetetin
approved these changes
May 21, 2026
aganglada
approved these changes
May 21, 2026
michalconsensys
approved these changes
May 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
9 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Per ADR #57. Removes committed agent skills/rules; switches install to the new public
MetaMask/skillsrepo, with the privateConsensys/skillsrepo available as an optional overlay for internal-only material.Why public
git clonea private repo or set engineer-managed env vars. The public repo solves this with a one-liner curl bootstrap (no SSH, no auth).postinstall.Engineer experience (zero-config)
Override only if you keep a separate clone:
Changes
development/skills-sync.mts— multi-source aware wrapper (was bash, ported to node.mtsto matchlint-changed.mts/lint-baseline.mtsconventions and avoid WSL/CRLF issues at the wrapper layer). Resolution order:METAMASK_SKILLS_DIR→CONSENSYS_SKILLS_DIR→ auto-fallback to.skills-cache/metamask-skills. When the cache is used, injectsMETAMASK_SKILLS_DIR=<cache>so the bash sync underneath sees the source.development/skills-postinstall.mts(new) — auto-clonesMetaMask/skillsinto.skills-cache/metamask-skillsand runs the installer on everyyarn install. Layered withCONSENSYS_SKILLS_DIRwhen set. Best-effort: skipped on CI, onSKILLS_SKIP_POSTINSTALL=1, or when offline. Opt back in on CI withSKILLS_FORCE_POSTINSTALL=1..gitignore— adds.skills-cache/, updates comments to reference public canonical.package.json—postinstallchain extended withnode development/skills-postinstall.mts;skillsscript usesnode development/skills-sync.mts..skills.local.example— documents new zero-config default + optional env-var override.Plus the original migration changes already in this branch: 12
.cursor/rules/, 3.claude/skills/, 2.cursor/skills/, 2.agents/skills/, 1.claude/commands/deleted (now covered by themms-*inject set)..skills.localper-engineer config gitignored.Companion PRs
MetaMask/skills(merged) — public source of truth, install CLI, multi-sourcesync, cloud-agentbootstrap.Consensys/skills#9— private overlay only; repo retained for future internal material.MetaMask/metamask-mobile#30180— parallel mobile migration.MetaMask/decisions#162— ADR amendment.Out of scope
Changelog
CHANGELOG entry: null
Related issues
Fixes: N/A — implements ADR #57.
Manual testing steps
yarn install. Confirm.skills-cache/metamask-skills/is populated and.claude/skills/mms-*etc. land under the repo.yarn skillswith no env vars set. Confirm it auto-detects the cache and writes/updates skills.SKILLS_DOMAINS=perps yarn skillsand confirm only perps skills install.yarn skills --selectand confirm the interactive picker appears.CONSENSYS_SKILLS_DIRset, runyarn skillsand confirm private overlay layers on top (private wins on name conflict).CI=1 yarn installand confirmpostinstallexits silently without writing anything.CI=1 SKILLS_FORCE_POSTINSTALL=1 yarn installand confirmpostinstallruns.METAMASK_SKILLS_DIR=~/dev/metamask/skillsand confirm it takes precedence over the cache.Screenshots/Recordings
N/A — developer tooling only, no UI changes.
Before
N/A
After
N/A
Pre-merge author checklist
Pre-merge reviewer checklist
Note
Medium Risk
Touches developer workflow by adding a
postinstallstep that clones/updates an external repo and changingyarn skillsto a wrapper that delegates to the synced CLI; failures should be best-effort but could still disrupt local installs in edge cases (offline/CI/Bash availability). No runtime product code is affected.Overview
Removes committed agent skills/rules under
.agents/,.claude/, and.cursor/(large markdown/yaml content), shifting skills content to be synced instead of versioned in this repo.Adds a new skills workflow:
postinstallnow best-effort clones/updates the publicMetaMask/skillsrepo into.skills-cache/, andyarn skillsis routed through a TS wrapper (development/skills-sync.ts) that resolves skill sources viaMETAMASK_SKILLS_DIR/.skills-cacheand an optionalCONSENSYS_SKILLS_DIRoverlay, plus enforces Bash 4+.Updates repo hygiene/docs for the new flow, including ignoring
.skills.localand.skills-cache/(and skill directories) and documenting the per-engineer config template in.skills.local.example.Reviewed by Cursor Bugbot for commit 69d1b60. Bugbot is set up for automated code reviews on this repo. Configure here.