typescript-expert
/typescript-expert
Expert TypeScript: type system, generics, narrowing, inference, and strict-mode safety. Trigger keywords: TypeScript, types, generics, type narrowing, tsconfig, strict, discriminated union, conditional/mapped types, utility types, declaration files, type error, satisfies, infer, any vs unknown. Use when writing/refactoring TS, fixing cryptic type errors, designing type-safe/generic APIs, or configuring the compiler.
- Author
- miaoge-ge ↗
- Repository
- coding-agent-skills ↗
- Licence
- MIT
- Last repository change
- 31.05.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 31.05.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Expert TypeScript: type system, generics, narrowing, inference, and strict-mode safety. Trigger keywords: TypeScript, types, generics, type narrowing, tsconfig, strict, discriminated union, conditional/mapped types, utility types, declaration files, type error, satisfies, infer, any vs unknown. Use when writing/refactoring TS, fixing cryptic type errors, designing type-safe/generic APIs, or configuring the compiler.
Original author description
Expert TypeScript: type system, generics, narrowing, inference, and strict-mode safety. Trigger keywords: TypeScript, types, generics, type narrowing, tsconfig, strict, discriminated union, conditional/mapped types, utility types, declaration files, type error, satisfies, infer, any vs unknown. Use when writing/refactoring TS, fixing cryptic type errors, designing type-safe/generic APIs, or configuring the compiler.
How it works
- When to Use
- When NOT to Use
- Core Principles
- Decision Guide
- Common Mistakes
- Examples
- See Also
SKILL.md preview
---
name: typescript-expert
description: "Expert TypeScript: type system, generics, narrowing, inference, and strict-mode safety. Trigger keywords: TypeScript, types, generics, type narrowing, tsconfig, strict, discriminated union, conditional/mapped types, utility types, declaration files, type error, satisfies, infer, any vs unknown. Use when writing/refactoring TS, fixing cryptic type errors, designing type-safe/generic APIs, or configuring the compiler."
---
# TypeScript Expert
> Make illegal states unrepresentable. Let inference do the work; annotate boundaries, not internals. `any` is a hole in the type system — reach for `unknown` + narrowing instead.
## When to Use
- Writing or refactoring TypeScript and wanting types that catch real bugs.
- A cryptic type error needs explaining or fixing (`not assignable`, `excessively deep`, variance complaints).
- Designing generic, reusable library types or public API surfaces.
- Configuring `tsconfig.json`, writing `.d.ts`, or migrating JS → TS.
## When NOT to Use
- Runtime/algorithm logic unrelated to typing → relevant language skill.
- React-specific component/hook patterns → `react-expert`.
- Backend framework wiring → `nodejs-backend-expert`.
## Core Principles
### 1. Strictness is non-negotiable
- `strict: true` is the floor. Add `noUncheckedIndexedAccess` (array access is `T | undefined`), and for libraries `exactOptionalPropertyTypes` + `noImplicitOverride`.
- Don't disable `strict` to "make it compile" — the error is usually a real bug. Fix the model.
### 2. `any` vs `unknown`
- `any` disables checking and silently spreads. Ban it (`@typescript-eslint/no-explicit-any`).
- At untyped boundaries (JSON, `catch`, 3rd-party) use `unknown`, then **narrow** with a guard or schema (`zod`) before use.
### 3. Let inference work; annotate intent
- Annotate function **parameters** and public **return types**; let locals infer.
- Use `as const` for literal tuples/objects, and `satisfies` to validate a value against a type **without widening** it (keeps the precise inferred type).
### 4. Model with the type system
- **Discriminated unions** for state/variants; a shared literal `kind`/`status` field unlocks exhaustive narrowing.
- Derive, don't duplicate: `ReturnType`, `Parameters`, `Awaited`, `keyof`, indexed access (`T["field"]`), `Pick`/`Omit`/`Record`.
- Newtype/branded types for domain values (`type UserId = string & { __brand: "UserId" }`) to stop mixing IDs.
### 5. Generics with constraints
- Add a type parameter only when callers vary the type. Constrain it (`<T extends ...>`) so errors surface at the call site, not deep inside.
- Use `infer` in conditional types to extract; avoid gratuitous deep conditional types (slow + unreadable).
## Decision Guide
| Situation | Use |
|-----------|-----|
| Object shape, may be extended/implemented | `interface` |
| Unions, intersections, mapped/conditional, tuples | `type` |
| Validate a literal without losing its narrow type | `satisfies` |
| Untrusted external data | `unknown` + `zod`/guard |
| One of N known variants | discriminated union + exhaustive `switch` |
| Prevent mixing same-typed domain values | branded type |
## Common Mistakes
- **Type assertions (`as`) to silence errors** → hides real mismatches. Narrow or fix the type instead; `as` only when you genuinely know more than the compiler (and add a comment why).
- **`enum`** → prefer `as const` union (`type Role = "admin" | "user"`); enums have runtime cost and odd semantics.
- **Non-null `!` everywhere** → masks `undefined` bugs; narrow with a guard or restructure.
- **`Function`, `object`, `{}` as types** → far too wide. `{}` means "anything but null/undefined".
- **Optional vs `undefined` confusion** → `a?: T` and `a: T | undefined` differ under `exactOptionalPropertyTypes`.
- **`any` in catch** → it's `unknown` since TS 4.4; narrow `if (e instanceof Error)`.
## Examples
**Discriminated union + exhaustive `never` check**
```ts
type Result<T> =
| { status: "ok"; data: T }
| { status: "error"; error: string };
function unwrap<T>(r: Result<T>): T {
switch (r.status) {
case "ok": return r.data;
case "error": throw new Error(r.error);
default: {
const _: never = r; // compile error if a new variant is added
return _;
}
}
}
```
**`satisfies` keeps precise inference while validating shape**
```ts
const routes = {
home: "/",
user: (id: string) => `/users/${id}`,
} satisfies Record<string, string | ((...a: any[]) => string)>;
routes.home; // type is "/" (not widened to string)
routes.user("42"); // typed callable
```
**Type predicate + branded id**
```ts
type UserId = string & { readonly __brand: unique symbol };
const asUserId = (s: string): UserId => s as UserId; // single controlled cast
function isNonEmpty<T>(a: T[]): a is [T, ...T[]] { return a.length > 0; }
```
## See Also
- `react-expert` — typing props, hooks, events, and generics in components.
- `nodejs-backend-expert` — typing handlers, config, and validated input.
- `api-design-expert` — sharing contract types across client/server.
- `refactoring-expert` — tightening types as a safe, incremental refactor.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · miaoge-ge/coding-agent-skills | 100 | MIT |
| rootcastleco/rei-skills | 100 | MIT |
| traylinx/switchAILocal | 100 | Apache-2.0 |
| personamanagmentlayer/pcl | 100 | Apache-2.0 |
| kumaran-is/claude-code-onboarding | 100 | MIT |
Database snapshot: 13.11.2026 · package version 6cb1cfb38b90 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100language
Guide for core TypeScript language features and the type system. Use when writing or reviewing TypeScript types, enabling strict mode, choosing a utility type, designing generics or conditional types, writing declaration files, or modeling data with discriminated unions. - 100typescript-type-safety
TypeScript type safety patterns - unknown vs any, generics golden rule, null narrowing, inference discipline, import type, discriminated unions, error typing. Use when writing or reviewing TypeScript code for type correctness. - 100typescript-ops
TypeScript type system, generics, utility types, strict mode, and ecosystem patterns. Use for: typescript, ts, type, generic, utility type, Partial, Pick, Omit, Record, Exclude, Extract, ReturnType, Parameters, keyof, typeof, infer, mapped type, conditional type, template… - 100typescript-patterns
TypeScript discipline for any JavaScript/TypeScript project (frontend + backend): strict mode, type design, generics, narrowing, error types, module resolution, tsconfig hygiene. Apply when the project has `tsconfig.json` and `typescript` in devDependencies. Stack-agnostic —… - 100typescript-strict
Use this skill when writing, reviewing, or fixing TypeScript where type safety matters — type errors, narrowing, unsafe casts, or tightening compiler strictness. Triggers: user mentions "TypeScript", "type error", "tsc", "strict", "type safety", "narrowing", "any", "unknown",… - 100developing-with-typescript
TypeScript 5.x development with type system, generics, utility types, and strict mode patterns. Use when writing TypeScript code or adding types to JavaScript projects.