The TypeScript Gap Isn't About Syntax. It's About the 90% of the Type System Nobody Uses.

There are two categories of TypeScript developer, and the boundary between them is not syntax.

Both categories write TypeScript every day. Both declare types, annotate functions, define interfaces. The gap between them isn't visible until something goes wrong — until a type that should be expressible can't be expressed, or a generic that should be composable has to be worked around with casts, or a utility type is reinvented instead of reached for.

The Advanced TypeScript Types skill from wshobson/agents is for the moment when your agent is operating at the TypeScript knowledge floor — technically correct, never wrong about syntax, but consistently not reaching for the tools that would make the type system actually work for you.

What's in the 90%

The TypeScript type system has capabilities that most developers don't encounter in tutorials or onboarding documentation.

Conditional types — T extends U ? X : Y — let you build types that branch based on type relationships. They're how TypeScript's built-in ReturnType<T> and Awaited<T> work. They're also how you build type utilities that eliminate entire categories of runtime errors by making impossible states inexpressible at the type level.

Mapped types let you transform one type into another systematically — iterate over keys, apply conditions, produce a new type that's derived from but not identical to the original. Partial<T>, Required<T>, Readonly<T> are all mapped types. The pattern behind them is learnable and composable, but most developers treat the built-in utilities as black boxes rather than understanding the underlying pattern they can apply themselves.

The infer keyword lets you extract type information from within a conditional type — pull the return type out of a function type, pull the element type out of an array, pull the resolved type out of a promise. Without infer, you hit a wall when you need to work with types you can't directly reference. With it, the wall disappears.

Template literal types turn string patterns into types, enabling things like typed CSS variables, typed API endpoint paths, and typed event names. This is where TypeScript's expressiveness becomes genuinely surprising.

Why Your Agent Doesn't Reach for These

The agents we use have read a lot of TypeScript code. They know the syntax. They know common patterns. They will produce correct TypeScript without needing the skill.

But the distribution of TypeScript in the training corpus is skewed. Most TypeScript in the wild is basic: interfaces, enums, function annotations, simple generics. The advanced type system features appear far less frequently, in specialized libraries and well-maintained open source projects — not in the average codebase.

This means the agent's default behavior under uncertainty is to reach for the simpler pattern. A cast instead of a conditional type. A manual type annotation instead of an inference. A concrete interface instead of a mapped type that would have eliminated duplicate definitions.

The agent isn't wrong. The simpler approach works. But it leaves you with a type system that provides less leverage than it could — types that describe rather than enforce, generics that accept more than they should, utility types that had to be written instead of derived.

What the Skill Changes

The Advanced TypeScript Types skill brings these patterns into the agent's default reach rather than its occasional awareness.

When you're building a type that transforms another type, the agent reaches for mapped types. When you need to extract type information from a generic, it reaches for infer. When a conditional type would make the relationship between input and output types explicit, it uses a conditional type.

37.5K installs suggests a specific audience: TypeScript developers who work on complex enough codebases that the advanced type system comes up regularly, and who have noticed their agent consistently not going there.

The skill doesn't add knowledge the model doesn't have. It adjusts what the model reaches for by default. For TypeScript, that adjustment is the difference between code that is typed and code that is well-typed.

The gap between those two things is not academic. It's the difference between catching a category of bugs at compile time or at runtime. It's the difference between a codebase where refactoring is safe and one where it requires careful manual verification of all the places a type is used.

TypeScript's type system is a capability. The skill is how you make sure your agent is using it.

---

Part of the AI Skill Daily series — skills worth understanding, one at a time.