typescript-engineer

TypeScript Engineer

Overview

Use this skill for type-level design, module-boundary type ownership, compiler-error diagnosis, and strict-safety refactoring in TypeScript. Route non-trivial work to the focused rule files in references/; do not answer from SKILL.md alone when the request involves advanced type behavior or shared type design.

Before any nontrivial repo work, read the target repo's AGENTS.md and CLAUDE.md overrides if they exist, then inspect the repo-local docs/TYPESCRIPT_STYLE.md or equivalent TypeScript instructions. The consumer repos are the source of truth for command front doors and local exceptions.

Design philosophy

• Keep one responsibility per file.
• Prefer small type modules with a single purpose over broad shared type dumping grounds.
• Split runtime behavior, runtime validation, and type-level helpers into separate files when they change for different reasons.
• Co-locate private helper types with the implementation that uses them.
• Promote a type to a shared file only after multiple modules need the same contract.
• Export stable contracts, not incidental implementation helper types.
• Treat API, storage, validation, and domain shapes as separate owners unless the repo proves they change together. For single-domain projects (browser games, CLIs, simple libraries) where some of those owners do not exist, fall back to feature-area boundaries inside the domain.
• Zero unchecked cast: as is permitted only inside a brand constructor, a type-guard return, or a documented boundary adapter. Never as a fix for a compiler error.
• Keep shared guidance narrow. When a consumer repo intentionally diverges, document the exception instead of flattening it into the shared rule.

When to use

• Untangle TypeScript compiler errors.
• Eliminate any, unsafe unknown handling, or unchecked casts.
• Design generics, conditional types, mapped types, template literal types, or branded types.
• Design shared contracts, DTOs, schema-derived types, domain models, or public type APIs.
• Refactor a file or module toward stricter compile-time safety without changing runtime behavior.
• Explain a TypeScript type-system concept with concrete before and after examples.
• Validate production refactors with tsc --noEmit and type-level tests.
• Follow the repo's shell-script front doors first: ./check_codebase.sh, ./build_github_pages.sh, ./run_web_server.sh, and ./run_playwright_tests.sh. Many repos also mirror these with npm run check, build, serve, and test:playwright, but the shell scripts remain the interface.
• Run repo Python helpers through source source_me.sh && python3 ... when the target repo uses the shared Python environment. Do not assume a bare python3 shell.
• Resolve a narrow in-flight type contract during a parallel game build (invoked by a coding subagent, not a manager). One bounded question -- typically a single shared type, brand, or boundary shape -- and a typed stub the caller can import. Not a full audit; see html-game-parallel-builder for the wrapper that triggers this case.