feat: install a base skill set by default

[andrepimenta]

What

Turns on a base skill set that installs for every engineer on a fresh clone, with no flags and nothing to read first. Mobile gets 10 skills; everything else stays opt-in.

The mandatory frontmatter flag is renamed to base and actually used. It was already implemented end to end — tools/install, tools/sync, the schema, the CLI, even a ★ marker in the interactive picker — but no skill had ever set it, and the default domain filter was permissive enough that the bypass had nothing to bypass.

Why

Three things had to be true together for "base skills by default" to work. Only the flag existed.

Problem	Fix
Empty SKILLS_DOMAINS meant all domains, so base never applied	none/all sentinels
SKILLS_AUTO_UPDATE was off by default, so postinstall refreshed the cache and installed nothing	Defaults on. The cache refresh moved behind the gate, so opted-out engineers no longer pay a network fetch per install
Six base descriptions were too thin to ever trigger	Rewritten. coding-guidelines was literally "General coding guidelines" — 25 characters

That last one is the subtle one: a skill's description is its entire trigger surface. A 25-character description never fires on the work it governs, while appearing to be covered.

Automatic vs explicit

yarn skills reads as "give me the skills", so having it install 10 instead of 36 would be a surprising regression for a command someone typed on purpose. The two paths differ:

Path	Domains	Installed
yarn skills, no config	all	36 — unchanged from today
yarn install → postinstall, no config	none	10
yarn install with SKILLS_DOMAINS=perps	perps	12 = 10 base + 2 perps
yarn skills --domain none	none	10

postinstall exports SKILLS_DEFAULT_SCOPE=base and tools/sync branches its fallback on that. Everything above the fallback in the resolution order is untouched — a --domain flag, SKILLS_DOMAINS, the picker, and a saved selection all still win.

That last property is the point of doing it this way. Passing --domain none from postinstall would have outranked a saved selection, so an engineer who opted into perps would have silently lost it on their next yarn install.

The base set (10)

mobile-testing · coding-guidelines · controller-integration · ui-development · component-scaffold · performance · pr-guidelines · create-pr · pr-description · pr-codeowners

pr-description and pr-codeowners are included because create-pr delegates its main output to them with "if available" phrasing — without them it silently runs in a reduced mode.

Always-on cost: ~1,130 tokens per session. The set is deliberately small: when the agent's skill listing overflows its budget, descriptions get truncated starting with the least-invoked skills, so a bloated base set makes every skill harder to trigger.

Safety

Enabling auto-update puts git operations on every engineer's install path, so this also:

• suppresses git credential prompts (GIT_TERMINAL_PROMPT=0, empty GIT_ASKPASS) in both run() and the delegated environment — tools/sync pulls the private Consensys overlay, which could otherwise block on stdin during yarn install with no output
• bounds every spawn: 300s for network git, 10s for local bash --version probes

Guardrails added

• base: true + maturity: experimental is now a lint error — contradictory intent; installing unfinished guidance for everyone is the bad outcome
• warns when a base skill's description is under 120 characters

Verified

Check	Result
Automatic path (SKILLS_DEFAULT_SCOPE=base)	exactly 10, in .claude/skills and .agents/skills
Explicit yarn skills	36
Automatic + SKILLS_DOMAINS=perps	12 — saved selection respected
SKILLS_AUTO_UPDATE=0 / CI=1	silent, exit 0
Full postinstall → sync → install	exit 0
Overlay merge intact	coding-guidelines 71-byte source stub → 3,990 bytes installed
node --test	65/65
lint-skill-entry.mjs	52 skills, 0 errors

Migration note

Existing engineers are not dropped to 10. Their current installs stay, because pruning is off by default and their next yarn install only adds the base set. yarn skills --prune-stale once gives a clean state.

This does reach external contributors: the skills package is a devDependency of public repos, so a drive-by contributor's yarn install now clones this repo into .skills-cache/ and writes 10 gitignored skill files. Public content, gitignored output, one clone — flagging it rather than letting it be discovered later.

Related

• Extension's base set: stacked PR on this branch
• Consumer side: feat: install base agent skills by default metamask-mobile#35263 (draft — needs a published release of this)

Known gaps documented separately: no standardized PR-review skill, platform APIs at 2 of ~11, and five deprecated testing skills that still compete with mobile-testing.

🤖 Generated with Claude Code

[NicolasMassart]

Blocking on the delegated postinstall path still being able to wait indefinitely.

[NicolasMassart]

Looks good to me.

[Qbandev]

Reviewed in depth — the diagnosis in the PR body is genuinely good (three gaps, one problem), and every number in it checks out against a clone at 637242a (65/65 tests, 0 lint errors, 10/36/12/4/0 domain counts verified). One blocker on top of @NicolasMassart's delegate() timeout comment, plus a few smaller items.

Blocker: legacy saved "all" selections are silently dropped to base-only.
The old picker returned empty output for the blank/'a' = "all [recommended]" choice, and the persist block wrote that as a literal SKILLS_DOMAINS= in .skills.local. After this PR, load_saved can't distinguish that from "no saved selection", so the [[ -n "$saved" ]] test fails and those engineers fall through to the new base-only fallback — reproduced end to end:

# legacy .skills.local with SKILLS_DOMAINS=
Domains: <base skills only>  (source: base only (automatic install …))   # 10 skills
# same file with SKILLS_DOMAINS=all
Domains: <all>  (source: saved (.skills.local))                          # 36 skills

This breaks the PR's own "a saved selection still wins" guarantee — and since pruning is off by default, the other 26 skills stay on disk and silently go stale rather than visibly disappearing. Small fix in load_saved (tools/sync:214): treat key-presence as "saved" and map an empty value to all:

load_saved() {
  [[ -f "$CONFIG_FILE" ]] || return 0
  grep -q '^SKILLS_DOMAINS=' "$CONFIG_FILE" || return 0
  local v; v=$(awk -F= '/^SKILLS_DOMAINS=/{sub(/^SKILLS_DOMAINS=/,""); print; exit}' "$CONFIG_FILE")
  echo "${v:-all}"
}

SSH prompts can still hang yarn install.
GIT_TERMINAL_PROMPT=0 + empty GIT_ASKPASS (bin/metamask-skills.mjs:272,411) don't affect ssh, which reads /dev/tty directly for passphrase/host-key prompts. The private Consensys overlay is documented as an SSH clone (tools/sync:166) and gets git pull --ff-only on every automatic sync — exactly the repo the Safety section names. Add GIT_SSH_COMMAND: 'ssh -oBatchMode=yes' alongside the existing two vars in both places. (Complementary to the delegate() timeout: the timeout bounds the hang, BatchMode prevents it.)

Smaller items:

• base: truthiness diverges across 4 implementations: the linter's TRUTHY accepts on (lint-skill-entry.mjs:36), but tools/install's is_truthy, tools/sync's domain_has_base regex, and the CLI's isTruthy don't. Verified: base: on passes lint as a base skill but the installer silently skips it — the exact failure mode the new lint rules exist to prevent. Simplest fix: drop on/off from the linter's sets.
• README:57 now states the opposite of the new behavior ("run sync only when SKILLS_AUTO_UPDATE=1") — both halves are false after this PR.
• No CHANGELOG entry, despite a breaking frontmatter rename (mandatory → base) and a default-behavior flip. Warrants 0.3.0.
• No tests for the new behavior — test/lint-skill-entry.test.mjs is a ready-made harness for the two new lint rules, and a test on the saved-selection resolution would have caught the blocker above.
• A typo'd domain (--domain nome) silently installs base-only with exit 0 — worth validating against list_domains() now that SKILLS_DOMAINS is the documented opt-in on a default-on path.

[andrepimenta]

All of this is addressed in c30fa37. Going through it in order — and two of your items led to finding a further bug each, which is noted below.

Blocker — legacy saved "all" dropped to base-only. Fixed, and your reproduction was exactly right. I took your load_saved shape but factored the key-presence + read into a shared read_config_value(), because SKILLS_MATURITY, SKILLS_INCLUDE and SKILLS_EXCLUDE all had the same awk-per-key duplication.

That refactor surfaced a second bug in the same readers: the JS side strips a trailing # comment via stripInlineComment(), the Bash side never did. Harmless while an unmatched domain just meant "install nothing extra" — but with the new validation you asked for below, it became a hard failure on the exact shape .skills.local.example teaches:

$ printf 'SKILLS_DOMAINS=perps # my choice\n' > .skills.local && yarn skills
Error: unknown domain(s): perps#mychoice  (source: saved (.skills.local))

So the validation and the comment-stripping had to land together; separately, the first would have broken configs the docs recommend.

SSH prompts. Fixed in both places — with one deviation: appended, not replaced.

return /(^|\s)-o\s*BatchMode=/u.test(base) ? base : `${base} -oBatchMode=yes`;

Hard-setting GIT_SSH_COMMAND would clobber a custom key, a 1Password/Secretive agent, or a ProxyCommand — on the private-overlay clone these guards exist to protect. And since buildDelegatedEnv() is shared, that would have hit the explicit yarn skills path too, not just postinstall.

base: truthiness across 4 implementations. Fixed — on/off dropped from the linter, which is now the same 1|true|yes as the other three. Related: tools/install now also accepts the pre-rename mandatory key, because executable code ships in the pinned package while domains/ content can come from the origin/main cache or a private overlay on its own cadence. Without the alias, that skew installs zero base skills and exits 0. It's registered as DEPRECATED_FRONTMATTER so the linter warns instead of reporting an unknown key.

README:57. Fixed.

CHANGELOG / 0.3.0. Added, including two **Breaking:** entries for the rename and the default flip. Agreed on 0.3.0 — the bump itself is left to create-release-pr.yml off ## [Unreleased] rather than hand-edited. Worth flagging for whoever cuts it: metamask-mobile pins ^0.2.0, which resolves >=0.2.0 <0.3.0 and therefore cannot reach 0.3.0. Publishing as 0.2.x instead would push both breaking changes to every existing consumer silently, so the pin has to move in lockstep.

Tests. Added to test/lint-skill-entry.test.mjs — 65 → 69, covering the description floor as an error rather than a warning (only errors set a non-zero exit, so as a warning it never actually failed a job), the boundary at exactly BASE_DESCRIPTION_MIN, short descriptions on non-base skills still passing, and base: on not being truthy.

Typo'd domain silently installing base-only. Fixed — validated against list_domains(), all/none exempted as sentinels.

This one also surfaced a sibling bug in --select: when every entered number was invalid, interactive_select returned "", which resolves to all. So an engineer who opened the picker specifically to narrow their set and then fat-fingered the numbers installed every domain. Blank already meant none; an all-invalid selection now means the same.

Supply chain (raised on the mobile PR, but the fix belongs here). tools/sync now execs $SCRIPT_DIR/install — the sibling of the pinned tools/sync that's already running — instead of preferring $METAMASK_SKILLS_DIR/tools/install. The cache still supplies domains/ content; it no longer supplies executable code. As you asked, this lands before the mobile dependency bump.

Verified on c30fa37: yarn lint:changelog passes, 69/69 tests, skill linter 0 errors across 52 skills.

Thanks — the two blockers were both real, and chasing them turned up two more.

[NicolasMassart]

Looks good. The previous blocking issues have been addressed, and I found no new blockers in the latest changes.

The domain-resolution logic would benefit from additional regression tests, but I don't consider that blocking.