Loaded automatically when its description matches the active task. Read only the section you need, then follow the link to the relevant reference file for full detail.
Writing or consuming .d.ts declaration files and declaration merging
Narrowing types safely: discriminated unions, type guards, asserts predicates
Migrating a JavaScript codebase to TypeScript incrementally
Diagnosing ts(xxxx) errors, understanding TS's structural type system
Do not use this skill when
Task is about running TypeScript at runtime on Node.js — use nodejs (type stripping, ts-node, build pipeline)
Task is React component prop types, hooks typing, or JSX generics — use react
Task is Vue typed templates, defineProps, defineEmits, or Composition API types — use vue
Task is Nuxt-specific typed composables or — use
defineNuxtConfig
nuxt
Task is linting or formatting TypeScript code (ESLint rules, Biome config) — use eslint or biome
Task is Prisma schema types or generated Prisma client types — use prisma
Task is schema validation at runtime (Zod inference, z.infer<>) — the runtime layer belongs to zod
Purpose
TypeScript's type system is Turing-complete at compile time — it can express almost any constraint your domain needs. In practice, most codebases stay in a shallow layer of basic types and any escapes, leaving correctness gaps that types were meant to close. This skill bridges that gap: it covers the full type-level programming surface of TS 6.0 — conditional types, mapped types, template literals, branded types, variance annotations — plus the config and tooling decisions that make TypeScript fast and maintainable in large monorepos.
TS 6.0 is a bridge release to TS 7 (Go-port). Key defaults changed: strict: true is now default, module defaults to esnext, target defaults to es2025, and types defaults to [] (no auto-load of all @types/*). Several module systems (amd, umd, systemjs) and flags (--baseUrl, --moduleResolution classic, --outFile) are removed/deprecated. esModuleInterop: false and allowSyntheticDefaultImports: false are no longer permitted. See references/migration.md for the upgrade checklist.
The skill deliberately scopes to the type-system layer only. It hands off to nodejs for runtime behavior, react/vue for framework-specific component types, and prisma/zod for ORM/validation type inference — those domains have their own type patterns that don't generalize. Here we focus on what is transferable across any TypeScript project: how to think in types, how to structure tsconfig.json for correctness and speed, and how to migrate safely from JavaScript.
Capabilities
Conditional & Mapped Types
The backbone of type-level programming. T extends U ? X : Y distributes over unions when T is a bare type parameter. infer extracts type variables from a matched shape. Mapped types iterate over a union of keys and transform each member. Combining them produces utility types that track domain invariants at the type level.
Key patterns: UnwrapPromise<T>, DeepReadonly<T>, PickByValue<T, V>, FlattenTuple<T>, recursive conditional types, as remapping in mapped types ([K in keyof T as Rename<K>]).
TS 5.x/6.x: template-literal types as discriminants, regex literal types (TS 5.9) validate string patterns at compile time. TS 6.0 improves inference for functions without explicit this usage (higher priority during type argument inference, fewer surprising generic errors).
Generics are parameterized type slots — not templates. Constraint rules: T extends object is structural, not nominal. NoInfer<T> (TS 5.4) blocks contextual inference for a type parameter, preventing accidental widening. const T (TS 5.0) captures literal types from arguments.
Variance annotations: in T (contravariant, write-only), out T (covariant, read-only). Explicit variance is 3–5× faster for type-check on complex generics compared to inferring it.
Higher-kinded types are not native in TS — simulate with interface mapping tricks or type-level dictionaries.
TypeScript is structurally typed — two shapes with the same fields are interchangeable. Branded types add a phantom tag that makes UserId and OrderId incompatible even if both are string underneath. Pattern: type UserId = string & { readonly __brand: "UserId" }. Constructor function enforces runtime creation.
satisfies operator (TS 4.9): validates a value against a type without widening — preserves the literal type of properties. Use instead of explicit annotation when you need both narrowing and type safety.
Sum types built on a common literal discriminant field. TS exhaustiveness check via never in a default branch. switch-on-discriminant fully narrows in each case. Better than class hierarchies for data modeling — no runtime overhead, no instanceof.
typeof, instanceof, in, equality narrowing, discriminant narrowing — TS understands all of these natively. Custom type guards: value is T return type. asserts value is T for throwing guards (eliminates null checks in callers). Control-flow narrowing with never for exhaustive branches.
Common narrowing pitfalls: narrowing doesn't survive Array.filter(Boolean) without an explicit predicate; closures captured after narrowing can widen back.
composite: true + references: [{path: "..."}] — tsc builds packages in dependency order, emits .d.ts declarations, and caches with .tsbuildinfo. Incremental builds are 10–50× faster than full rebuilds on large monorepos.
paths in tsconfig.base.json + moduleNameMapper in Jest/Vitest aligns resolver behavior. verbatimModuleSyntax prevents spurious re-exports. Turborepo / Nx coordinate build ordering; TS project references handle type correctness independently.
Three levers: (1) incremental + tsBuildInfo — skip files with no changes; (2) skipLibCheck: true — skip type-checking in node_modules; (3) isolate heavy paths — if one package has complex generics, split it into its own project reference so only it re-checks when it changes.
Profile with tsc --diagnostics and tsc --extendedDiagnostics. Common bottleneck: overly deep recursive conditional types — flatten via infer at an intermediate step.
