Skip to content
Skills Library
Programming · Building & coding

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.

Licence
MIT
Last repository change
31.05.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 31.05.2026, without references to retired models or APIs.

Licence

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

  1. When to Use
  2. When NOT to Use
  3. Core Principles
  4. Decision Guide
  5. Common Mistakes
  6. Examples
  7. See Also
Original SKILL.md headings · 100 lines, 709 words
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

RepositoryScoreLicence
This page · miaoge-ge/coding-agent-skills100MIT
rootcastleco/rei-skills100MIT
traylinx/switchAILocal100Apache-2.0
personamanagmentlayer/pcl100Apache-2.0
kumaran-is/claude-code-onboarding100MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.