feat(typescript): add tsc-blindspots and type-safe authoring, JS->TS migration skills

[MajorLift]

Adds a typescript domain with five experimental skills — the reasoning layer for TypeScript authoring and JS→TS migration that coding-guidelines only gestures at.

Why it earns a place as an extension skill: the extension is a large, ongoing JS→TS migration authored increasingly by AI agents (Claude, Cursor, Codex, headless cloud agents). Three failure modes recur under conversion pressure — reaching for any, hand-writing ad-hoc types that duplicate an authoritative source, and converting a multi-thousand-line file in one unreviewable pass. @typescript-eslint/no-explicit-any is a CI hard-gate for the first; the reasoning behind all three is un-lintable and belongs in a skill that reaches every operator.

Skills

• avoid-any — any is a directive that disables type checking, not a wide type. Substitute by position (assignee → unknown, assigned → never); the one exception is a generic constraint, declared with an inline eslint-disable.
• derive-types — derive from authoritative sources (indexed access, typeof, ReturnType/Parameters, Pick/Omit, Infer<typeof struct>) instead of ad-hoc types that duplicate, run too wide, and drift. Grounded in a real extension counterexample (#42583).
• decompose-large-files — decompose a large file by coherent, independently-mergeable units to improve modularity, maintainability, and reviewability, and to unblock incremental TS migration. Extract by coherent subject; never fragment for its own sake. Modeled on the MetamaskController decomposition (#41735).
• migration-context-cost — reason about the fan-in/fan-out cost of a conversion: how much context a file drags in, and therefore whether it is a cheap first migration or one that pulls half the repo with it.
• tsc-blindspots — find the type defects tsc is structurally unable to report. A green build is not evidence the types are correct: hand-written types that restate an authoritative source can disagree with it, and the language and config carry standing blind spots.

Grounded in MetaMask/contributor-docs docs/typescript.md. Shipped experimental (opt-in via --maturity experimental); no repos/ overlay, so it applies to metamask-extension, metamask-mobile, and core alike. Commits GPG-signed.

tsc-blindspots lives here rather than in testing (it supersedes #85, which placed it there). Its subject is whether a hand-written type agrees with its authoritative source — the question derive-types answers from the authoring side, one step earlier. Both rest on this domain's premise that a green tsc proves well-formedness, not correctness; in a partially-migrated repo with checkJs off it often cannot prove even that. It ships scripts/substitution-ab.sh plus three references.

---

Validation runs

Trial runs of this PR's skills against merged metamask-extension PRs nobody flagged. Every claim was re-verified against the real diff before posting. Clean results are included on purpose — a skill that only ever reports problems cannot be calibrated.

PR	Skill	Verdict	Finding
#41333	tsc-blindspots	Gap	local type restates upstream Log.topics; naive probe reports false clean

Each comment carries a trial-run disclaimer and links back here for feedback.

[MajorLift]

Context budget

What this PR costs an agent, measured from an install rather than read from the diff. Three tiers, and only the first is unavoidable.

Skill	Frontmatter	Selected	+ refs & knowledge
avoid-any	359 chars	~1,605 tok	~1,605 tok
decompose-large-files	266 chars	~1,612 tok	~1,612 tok
derive-types	210 chars	~1,168 tok	~1,168 tok
migration-context-cost	243 chars	~781 tok	~781 tok
tsc-blindspots	1,244 chars	~3,406 tok	~8,327 tok

Frontmatter is the only tier paid unconditionally — every agent loads it on every run once the skill is installed, used or not, because it is what the agent reads to decide relevance. The 28 skills across the eleven open skill PRs sit at a median of ~1,716 tokens selected and ~1,860 with references followed. All are within the 1,536-character description budget.

Selected is paid only when the agent picks the skill. + refs & knowledge is the ceiling if every bundled reference is then read; it is a worst case, not an expectation.

Method

tools/install --repo metamask-extension --maturity experimental against this branch at e170b394c, measured per installed skill directory. Repo overlays are merged into the emitted SKILL.md, so they land in the selected tier rather than being missed by a source-byte count. Token figures are bytes/4 — a proxy for scale, not accounting.

These figures are pinned to the commit above and drift on every push; #96 tracks automating them.