Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

typescript-standards

Use when writing, reviewing, or architecting TypeScript in app or library code. Don't use for test-only files, docs, CSS, or helper placement (that is a different search).

AlemTuzlak · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add AlemTuzlak/skills --skill typescript-standards

About this skill


name: typescript-standards description: Use when writing, reviewing, or architecting TypeScript in app or library code. Don't use for test-only files, docs, CSS, or helper placement (that is a different search).

TypeScript Standards

Public APIs must feel like JavaScript. Callers write JS. You hide the type work. App or library does not change this.

This skill does not decide where a helper file lives. It does not add debug flags. It does not load other skills.

When To Use

Load when writing or reviewing TypeScript (.ts, .tsx). App code and library code both use these rules.

Skip test-only files, docs, and CSS.

Hard Gates

  1. Call sites never write <T>. If they must, the signature is wrong. Generic definitions are fine.
  2. Never write overloads. One signature. Derive the return with inference and conditional types.
  3. No as any, as unknown as X, or cast chains. If you need as, the types are usually wrong.
  4. as const only to stop widening (e.g. "open" staying "open", not string). Not a habit.
  5. Do not annotate function return types. Let TypeScript infer. Do not write : Foo after ).
  6. If the function cannot work without a value, that value is required. Do not take T | undefined and return early. Do not accept the property.
  7. Pipe types through callers. If A needs B, C that calls A takes B. Do not take a looser type in C and cast inside C.
  8. Fix this skill’s smells only in the file you already opened. Do not tour the folder.

Inference

Design signatures so TypeScript infers from arguments and returned values.

createStore({ count: 0 })

not

createStore<{ count: number }>({ count: 0 })

Do not write the return type on the function. Infer it from return.

Types

  • Before a new type or interface, search the current package and neighbors. Use or extend the one that is the same shape. Do not grep the whole monorepo for a one-file type.
  • One signature. Conditional types when the return depends on the input. No overload list.
  • Constrain with types, not with runtime typeof / extra unions. function f(b: string) not function f(b: string | undefined) { if (typeof b === "string") ... }.
  • Arrays stay constrained. arr.map(a => ...) infers a. Do not write arr.map((a: Foo): Bar => ...).
  • filter / narrow with a type predicate: (value): value is X. Do not leave the array as a loose union after a filter that is meant to narrow.
  • Do not loosen types “just in case.” If the code cannot run without a field, that field is required on the argument.

Functions

  • First arg is the required value (URL, input, id).
  • Extra flags go in an options object when a lone boolean is unclear (fn(url, true)) or when there is more than one extra. add(a, b) stays two values.
  • Options/setup must still work if pulled into a helper. If extraction breaks types or behavior, fix the signature. Do not extract every options object by default.
  • Return the type the caller needs, including nullish. If the next function wants X | null, return X | null. Do not return X | undefined and then x ?? null. Pick null or undefined for that path and keep it.
  • Name complex conditions:
const isOpenGold = order.status === "open" && order.tier === "gold"
if (isOpenGold) { /* ... */ }

Do not dump a long && / || chain into if (...).

  • Early return to narrow. Prefer an early if over nested else. For several missing values, one if with ||:
if (a === null || a === undefined || b === null) return

Then use a and b as defined. Do not write if (a !== null || a !== undefined) (that check is always true).

  • Three or more branches on the same value: exhaustive switch. Use a never default (or no default with a union the compiler checks). Do not write a ladder of if / else if.
  • Loops: assign the list first, then iterate.
const values = getValues(input)
for (const value of values) { /* ... */ }

Do not call getValues in the for header.

  • Spreads stay flat. { ...a, b: { ...c } }. Do not convert fields in the spread (c.x === undefined ? null : c). If every call site converts format A to format B, the data model failed. Convert once at a boundary, or change the types so both sides match.
  • Public functions (package entry, exported SDK, what users call) get TSDoc: what it does, the arguments, how to call it. Do not annotate the return type in the signature. You can describe the result in the comment.

Casts

Banned: as any, as unknown as X, double casts, (x as any).code.

Allowed:

  • as const only when a literal widens (string/number/array) and you need the literal type.
  • return x as T only when TypeScript cannot infer a generic return (e.g. JSON.parse into T). Still do not write : T on the function.

Errors

Custom Error subclasses only at a boundary callers catch (exported function, SDK, route handler). Internal helpers can throw new Error(...). Document on that boundary (TSDoc) what can throw and which class to catch.

Barrels

No export *. Inside the repo, import from the real file. The package public entry (index.ts behind exports) can re-export named symbols only.

Procedures

Procedure 1: Before a new type or signature

  1. Search the current package and neighbors for an existing type.
  2. Write one function signature. Infer from args and from return. No overloads. No call-site <T>. No return annotation.
  3. If the body cannot run without a field, that field is required. Do not take it as optional.
  4. If this function calls another that needs type B, this function takes B.
  5. If extras are a magic boolean, use an options object.
  6. If the function is public, write TSDoc (what, args, how to use).

Procedure 2: While editing

  1. Do not add banned casts. as const only for widening. Do not add return type annota
Read the complete source ↗