feat: add the metamask-extension base skill set

[andrepimenta]

⚠️ Merge after #135

Stacked on feat/base-skills-mobile. The base flag this PR sets is introduced there — merge #135 first, then this retargets to main automatically.

What

Marks the 10 skills every metamask-extension engineer needs as base, so a fresh clone lands exactly those.

Four are already shared with Mobile and land in #135 — coding-guidelines, ui-development, controller-integration, pr-guidelines. This PR adds the six Extension-only ones:

Skill	Why base
extension-testing	Testing entrypoint — unit, integration (stub), Selenium E2E
controller-guidelines	Authoring a controller: BaseController choice, state metadata, messenger typing
perf-rendering	Lists, virtualization, memoization, code splitting
perf-hooks-effects	useEffect misuse, dependency arrays, cascading effects
perf-react-compiler	What the compiler optimizes, where it bails out, when manual memoization remains
perf-state-management	Redux reducer purity, selector identity, normalization

Always-on cost: 3,257 characters ≈ 814 tokens per session across all ten.

Descriptions

Both caveats from the original version are addressed.

Descriptions now state trigger conditions, not topics. They were 34–39 characters — "Rendering performance optimization" says what a skill is about but never when to reach for it, and nobody phrases the problem that way; they say the list stutters when they scroll. Each now leads with concrete coverage and ends with a Use when … clause in symptom vocabulary.

The original mitigation here — "CI warns on each until rewritten, so the TODO cannot rot" — was false, as @Qbandev demonstrated: the linter only sets a non-zero exit on errors, so a warning sat invisibly inside a green check. #135 promotes the base-description floor to an error, which is what makes this PR's descriptions load-bearing rather than optional.

The four perf-* skills now route to each other. They were mutually indistinguishable — "my component re-renders too much" matched all four equally, so selection was arbitrary and the model could pull ~20KB scattershot. Each now names its siblings, so whichever fires hands off rather than competing.

This mitigates the four-slots-for-one-concern problem; it does not solve it. Consolidating to a single entrypoint with on-demand references, as Mobile's performance does, remains the structural fix and is still worth doing separately.

Nothing here is measured. The argument is mechanical — the description is the selection surface, symptoms were absent, siblings were undifferentiated — not the result of a triggering experiment.

Scope

Proposed from the catalogue rather than from working in metamask-extension, so it still needs owner review on:

• whether extension-testing is genuinely the right single testing entrypoint

Resolved since the original: @MajorLift confirmed controller-guidelines and controller-integration should both be base, with controller-integration the more valuable for client work since integrating controllers is routine and authoring them is not. They now cross-reference each other, and controller-integration's Extension reference gains a section pointing at the authoring guidance.

Known Extension gaps (not addressed here)

Gap	Notes
Almost no PR automation	9 of 10 pr-workflow skills are Mobile-only, including create-pr. Extension gets PR standards but no PR automation. Overlay work on existing skills — likely the cheapest high-value win.
No component-scaffold equivalent	Design-system-first intent has no enforcement at generation time
No component-view test layer	The "steer agents toward component view tests" goal is Mobile-only today
Platform APIs	1 of ~11 areas covered

[NicolasMassart]

One concern before treating the proposed Extension set as the default base.

[NicolasMassart]

suggestion: fix the perf trigger descriptions before making these base

The PR already calls out that the four perf-* descriptions are too thin to self-trigger.

That seems at odds with #135's rationale for the base-description guard: a base skill permanently consumes listing context, so installing one that rarely triggers gives us the cost without much benefit.

Could we either improve these descriptions in this PR before marking them base, or leave the perf skills opt-in until that cleanup is done?

[andrepimenta]

Agreed — and as of c30fa37 on #135 this is no longer a judgment call, it's a build failure.

That commit turns the base-description floor from a warning into an error (@Qbandev's point below: warnings never set a non-zero exit, so "CI warns until it's rewritten" wasn't actually a ratchet). Since this branch is stacked on feat/base-skills-mobile, it inherits that on the next rebase. Verified by linting this branch's content with the post-#135 linter:

$ SKILLS_LINT_ROOT=<clone of feat/base-skills-extension> node .github/scripts/lint-skill-entry.mjs
coding/controller-guidelines
  error: `description` is only 35 chars; a base skill needs enough trigger cues …
performance/perf-hooks-effects      error: … only 36 chars …
performance/perf-react-compiler     error: … only 36 chars …
performance/perf-rendering          error: … only 34 chars …
performance/perf-state-management   error: … only 39 chars …

52 skill(s) checked, 5 error(s), 90 warning(s)
$ echo $?
1

So of your two options, "improve the descriptions in this PR" and "leave them opt-in until the cleanup" are now the only two — marking them base as-is can't merge.

One correction to the framing: it's 5 skills, not 4. controller-guidelines has the identical defect at 35 chars but was presented in the inclusion table without the caveat. Credit to @Qbandev for catching that one.

[Qbandev]

Verified against a clone of feat/base-skills-extension: repo scoping is airtight (simulating the repos/${REPO}.md gate gives extension 10, mobile 10, core 0 — the body's claim is exact), and 65/65 tests / 0 lint errors reproduce. Three things before marking these base:

The thin-description problem covers 5 of the 6 skills, not 4.
@NicolasMassart's comment targets the four perf-* skills, but controller-guidelines has the identical defect — description is "BaseController development patterns", 35 chars — while being presented in the inclusion table without a caveat. Only extension-testing (389 chars) clears the 120-char BASE_DESCRIPTION_MIN floor that #135 introduces. Full audit on this branch: perf-rendering 34, controller-guidelines 35, perf-hooks-effects 36, perf-react-compiler 36, perf-state-management 39.

"CI warns on each until rewritten, so the TODO cannot rot" doesn't hold.
lint-skill-entry.mjs sets process.exitCode = errorCount > 0 ? 1 : 0 — warnings never fail the job. The audit on this branch reports 0 errors and 95 warnings; the five base-description warnings would sit invisibly inside a green check. If the intent is a real ratchet, the base-description rule needs to be an error for base: true skills.

The "~670 tokens/session" figure appears to be characters.
Summing name + description across the six skills gives 679 characters ≈ 170 tokens. #135's "~1,130 tokens" is a genuine token estimate (4,221 chars ÷ ~4), so the two headline numbers are on different scales.

Suggestion: mark extension-testing base now; hold the other five until the descriptions are rewritten to 120+ chars (which also resolves whether four separate perf slots vs. Mobile's single-entrypoint shape is the right structure). Separately: the five stubs omit maturity: entirely, so #135's new base + experimental guard never evaluates them — adding explicit maturity: stable makes the stability claim deliberate.

[MajorLift]

This list overlaps almost entirely with the list of skill pointers we have in extension's AGENTS.md file:

### Coding Guidelines

- **Controller Patterns:** [.cursor/rules/mms-controller-guidelines/RULE.md](./.cursor/rules/mms-controller-guidelines/RULE.md)
- **Unit Testing:** [.cursor/rules/mms-extension-testing/RULE.md](./.cursor/rules/mms-extension-testing/RULE.md) → `references/unit.md`
- **E2E Testing:** [./test/e2e/AGENTS.md](./test/e2e/AGENTS.md) and [.cursor/rules/mms-extension-testing/RULE.md](./.cursor/rules/mms-extension-testing/RULE.md) → `references/e2e.md`
- **E2E CI Decision Tree:** [.github/guidelines/E2E_DECISION_TREE.md](./.github/guidelines/E2E_DECISION_TREE.md)
- **E2E Deprecated Patterns:** [./test/e2e/AGENTS.md](./test/e2e/AGENTS.md)
- **CI Workflows:** [.github/AGENTS.md](./.github/AGENTS.md)
- **Front-End Performance:**
  - [Rendering Performance](.cursor/rules/mms-perf-rendering/RULE.md) - Start here (keys, memoization, virtualization)
  - [Hooks & Effects](.cursor/rules/mms-perf-hooks-effects/RULE.md) - useEffect best practices
  - [React Compiler & Anti-Patterns](.cursor/rules/mms-perf-react-compiler/RULE.md) - React Compiler considerations
  - [State Management](.cursor/rules/mms-perf-state-management/RULE.md) - Redux optimization
- **Pull Requests:** [.cursor/rules/mms-pr-guidelines/RULE.md](./.cursor/rules/mms-pr-guidelines/RULE.md)
- **General Coding:** [.cursor/rules/mms-coding-guidelines/RULE.md](./.cursor/rules/mms-coding-guidelines/RULE.md)
- **Official Guidelines:** [.github/guidelines/CODING_GUIDELINES.md](./.github/guidelines/CODING_GUIDELINES.md)

-- https://github.com/MetaMask/metamask-extension/blob/main/AGENTS.md#coding-guidelines.

Setting aside the fact that the file badly needs to be cleaned up, I think it's a good indication that this PR covers the category of skills that need to be "accessible by default."

However, there's another category of critical skills that need to be "discoverable by default", a) because they otherwise would not be human-invoked or agent-searched due to lack of awareness, or b) because they actively correct agent (or human) predispositions that are erroneous. From experience reviewing extension PRs, these skills have contributed useful or even mission-critical interventions, and would be valuable to include as base skills:

Skill	Why it needs to be discoverable
observability/sentry-quota span instrumentation whose fan-out is quota-risky	not invoked or discovered — The only feedback is the bill, after release. Engineers are not aware this needs to be checked (sometimes they're even unaware they're activating new instrumentation) so the skill is not invoked when it's most needed -- discovery is the only option. This awareness gap has resulted in multiple incidents over the past couple months.
privacy/data-egress-diligence changes to what user data leaves the device — Sentry state masks, new MetaMetrics/Segment properties	not invoked or discovered — Data is sent irrevocably, but no test fails, no user reports it, and the mask list is not something a reviewer thinks to check, so engineers are not aware there's a problem. Intervention via skill discovery at authoring time is the critical intervention point.
security/deeplink-handler a new deep link route, or an existing one re-pointed	not invoked or discovered — An author who does not know the security model of the deeplink interstitial boundary (or even that the boundary exists) has no reason to search for this skill, and the resulting defects have recurred in review resulting in reverts e.g. allowlists written as plain object literals, which admit every prototype key, and validated params that never reach the destination. Discovery at authoring time is the only mechanism that puts the boundary in front of the author.
platform/extension-lifecycle-decoupling lifecycle events assumed to cause application-level side effects	corrects a predisposition — Preempts confidently wrong MV3 claims that have been prevalent enough to be disruptive to platform team, e.g. frequent reports that all manner of bugs are attributable to service worker frequently dying mid-session (it doesn't die due to a keepalive).
typescript/tsc-blindspots type defects tsc is structurally unable to report	both — Engineers are not aware that there's a problem as long as tsc returns green status, even though tsc can ratify incorrect and unsafe types because it only checks branch-internal consistency, not correspondence to authoritative type sources.
typescript/derive-types hand-written ad-hoc types that restate an authoritative source	corrects a predisposition — writing ad-hoc inline types even when they can and should be derived from authoritative sources is a strong agent predisposition that needs to be preempted
performance/effect-antipattern-scan effects synchronising state derivable during render, dependency arrays that lie	both — Engineers writing defective code are not aware there's a problem, and therefore cannot invoke this skill. Defects have no symptom at authoring time, and fail silently at runtime, only being detectable through active profiling. Only static code analysis via gate or skill discovery preempts the error and closes the gap.
performance/selector-antipattern-scan selectors returning a fresh identity per call, cascading renders	both — Same as above.

Together they add 6,964 characters of always-loaded description, against 1,528 for the eleven AGENTS.md already points at, but I think the two are worth separate budgets. It's more efficient and reliable to specify the "needs to be accessible" category discovery conditions in AGENTS.md, while the "needs to be discoverable" category MUST have its descriptions always-loaded in context.

The additional skills can be added in a follow-up once they've been merged, but I think they're critical to include.

[MajorLift]

If we're only choosing one controller-related skill for extension it should probably be controller-integration(https://github.com/MetaMask/skills/blob/main/domains/coding/skills/controller-integration/repos/metamask-extension.md), since writing controllers is not a client-side concern, while integrating them comes up very frequently.

We can probably fit in both if wider understanding of controller internals seems valuable to have by default (or better yet have controller-integration reference sections of controller-guidelines so relevant information can be pulled by the agent as needed), but either way controller-integration would need to be included.

[andrepimenta]

Agreed on the priority, and the good news is that half of it is already done: controller-integration is base in #135, not here. It carries a repos/metamask-extension.md overlay, so extension engineers get it from that PR regardless of what happens to this one. This thread is therefore only about whether controller-guidelines should be base in addition.

That question is now forced by CI. controller-guidelines is one of five skills failing the base-description floor that #135 (c30fa37) promoted from a warning to an error:

coding/controller-guidelines
  error: `description` is only 35 chars ("BaseController development patterns");
         a base skill needs enough trigger cues to be selected (aim for 120+)

So it can't be marked base as written, independent of the design question.

Your parenthetical is probably the best resolution: have controller-integration reference the relevant sections of controller-guidelines so the agent pulls internals on demand. That keeps the content reachable without spending a second always-on listing slot, and it matches the shape Mobile uses — one entrypoint plus on-demand references — which @Qbandev independently raised about the four separate perf-* slots. Same structural fix for both.

Your point about writing controllers not being a client-side concern is also the stronger argument for why it should be on-demand rather than always-on, so those line up.

[andrepimenta]

All three verified, and the second one is now implemented upstream in #135.

1. Five skills, not four. Confirmed exactly, including your character counts. Reproduced by linting this branch's content with the post-#135 linter:

coding/controller-guidelines       35
performance/perf-rendering         34
performance/perf-hooks-effects     36
performance/perf-react-compiler    36
performance/perf-state-management  39

extension-testing at 401 chars is the only one that clears the floor — matching your read.

2. "CI warns until rewritten" doesn't hold. Correct, and fixed. c30fa37 on #135 moves the base-description rule from warnings.push to errors.push, exactly as you suggested, with tests covering the boundary at BASE_DESCRIPTION_MIN, short descriptions on non-base skills still passing, and base: on not being truthy. The consequence lands right here: this branch now exits 1 with 5 errors on rebase, so the thin descriptions are a merge blocker rather than an invisible warning.

That was the most useful thing in your review — a ratchet that never fails a job isn't a ratchet.

3. Characters vs tokens. Confirmed. I get 691 chars ≈ 173 tokens summing name + description across the six (marginally different from your 679/170, just folded-scalar parsing). Either way the PR body's "~670 tokens" is a character count wearing a token label, and the real always-on cost is ~4× smaller than advertised. Worth fixing in the body, since #135's "~1,130 tokens" is a real token estimate and the two currently aren't comparable.

4. Missing maturity:. Good catch — the five stubs omit it, so #135's new base + experimental guard never evaluates them. Explicit maturity: stable makes the claim deliberate rather than defaulted.

On the suggestion — mark extension-testing base now, hold the other five — that's now the path of least resistance rather than just the tidier one, since CI enforces it either way. It also defers the four-perf-slots-vs-one-entrypoint question to the same cleanup, which is where it belongs; @MajorLift suggested the analogous fix for controller-guidelines (reference it from controller-integration rather than giving it its own slot).

[andrepimenta]

The accessible/discoverable split is the most useful framing anyone has put on this, and I think it's right. AGENTS.md pointers work fine for a skill someone already knows to reach for; they do nothing for the case where the entire value is that the author doesn't know there's a problem. A pointer list can't fix an awareness gap, because reading it is already the thing that isn't happening. Those genuinely need the description resident in context, and that's a different budget line, not a bigger version of the same one.

Three practical notes for the follow-up:

They'll each need to clear the 120-char floor — and that's now an error, not a warning. c30fa37 on #135 promoted BASE_DESCRIPTION_MIN from warnings.push to errors.push. From the descriptions you quoted these look like they'd pass comfortably (they read as trigger-condition prose rather than labels, which is exactly what the rule is trying to select for), but it's worth confirming before marking them, because five of the six skills in this PR fail it — this branch currently exits 1 with 5 errors once rebased.

Your set is arguably the better argument for the rule than the rule's own rationale: a skill that exists specifically to be discovered by someone unaware of the problem is precisely the one where a 35-char label is fatal.

Putting the budgets on one scale. The PR body's "~670 tokens" turned out to be a character count (@Qbandev caught it); real figures, all name + description, ÷4:

Set	Chars	~Tokens
#135 shared base	4,221	~1,055
#136 extension additions	691	~173
Your 8 "discoverable"	6,964	~1,741

So the discoverable set is larger than the other two combined. That doesn't argue against it — the incident history you're describing is a much stronger justification than 1.7k tokens is a cost — but it does mean it deserves its own decision rather than riding in as an increment, which is what you're proposing anyway.

Sequencing. Those four domains (observability, privacy, platform, typescript) don't exist on main yet — current set is assets coding general performance perps pr-workflow swaps testing ui web3-tools — so follow-up is the only option regardless. Worth landing them as a single deliberate PR with the category rationale in the body, rather than folding them into a base-set expansion, so the "discoverable" budget is reviewable as its own thing.

On the AGENTS.md cleanup: agreed it needs it, and there's a nice consequence — once a skill is base, the pointer to it in AGENTS.md is redundant by construction. That's a decent test for whether the two lists are drifting.

[andrepimenta]

Pushed b0edb06 — descriptions rewritten, rebased onto the current #135 head, and the PR body updated to match.

Both caveats are now addressed. Descriptions were 34–39 chars; they're now 247–339 and each ends with a Use when … clause in symptom vocabulary rather than naming a topic. The four perf-* skills also cross-reference each other, so "my component re-renders too much" no longer matches all four equally — whichever fires hands off instead of competing.

That mitigates caveat #2 rather than solving it. Consolidating to a single entrypoint with on-demand references, the shape Mobile's performance uses, is still the structural fix and still worth doing separately.

@NicolasMassart — your suggestion is now enforced rather than advisory. Worth knowing it was 5 skills, not 4: controller-guidelines had the same 35-char defect but sat in the inclusion table without a caveat.

@Qbandev — all three points landed. The "CI warns so the TODO cannot rot" mitigation was indeed false, and that's the finding that changed the code: #135 promotes the floor from a warning to an error, so these descriptions are load-bearing rather than optional. The "~670 tokens" figure was a character count; the ten base skills now cost 3,257 chars ≈ 814 tokens. maturity: on the stubs is not yet added — omitting it already defaults to stable, so it's a clarity change rather than a behaviour one; happy to fold it in if you'd prefer it explicit.

@MajorLift — took the second option on controllers. Both stay base, and controller-integration's Extension reference gains a section pointing at controller-guidelines for the authoring internals, so the split is discoverable rather than confusing. Agreed that integrating controllers is the routine client-side task and authoring them is not.

Two things worth flagging on this branch:

1. It was previously based on e2f6533, the first commit of feat: install a base skill set by default #135 — three commits behind its own base, from before the description floor became an error. Its green CI was therefore uninformative. It's now rebased onto c30fa37, so the checks genuinely exercise the rule.
2. An earlier revision also tightened coding-guidelines, pr-guidelines and ui-development. Those are shared with Mobile and already passed the floor, so changing them here would have put mobile-visible edits inside an Extension PR. Reverted — this branch now touches 8 files, all Extension-scoped bar controller-integration, which was already base for both.

Still open: nothing is measured. The case for these descriptions is mechanical, not the result of a triggering experiment.