TY

typescript-write

Enforces strict TypeScript/JavaScript standards including no-any rules and mandatory LSP verification.

Install

mkdir -p .claude/skills/typescript-write && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/21" && unzip -o skill.zip -d .claude/skills/typescript-write && rm skill.zip

Installs to .claude/skills/typescript-write

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Write TypeScript and JavaScript code following Metabase coding standards and best practices. Use when developing or refactoring TypeScript/JavaScript code.
155 chars✓ has a “when” trigger
Advanced

Key capabilities

  • →Refactor code to remove any types
  • →Tighten function signatures using generics
  • →Verify changes using TypeScript Language Server
  • →Model data contracts with discriminated unions
  • →Implement type guards for boundary values

How it works

The skill enforces strict typing by prohibiting 'any', mandating LSP verification, and requiring the use of specific type-modeling patterns like discriminated unions and generics.

Inputs & outputs

You give it
Untyped or loosely typed JavaScript/TypeScript code
You get back
Strictly typed code adhering to Metabase standards

When to use typescript-write

  • →Refactoring code to remove 'any' types
  • →Writing new typed components
  • →Tightening function signatures
  • →Performing LSP verification on changes

About this skill

TypeScript/JavaScript Development Skill

Before frontend edits, including test-only changes, read frontend/AGENTS.md, docs/developers-guide/frontend.md, and the shared references below. For new or edited tests, follow Test authoring.

@./../_shared/development-workflow.md @./../_shared/typescript-commands.md @./../_shared/react-redux-patterns.md

No any — hard rule

  • New, moved, or otherwise edited code must not contain any, explicit or implicit. No any annotations, no as any / as unknown as, no untyped parameters or returns that infer any, no implicitly-any destructures or array/object literals.
  • Stop untyped values at the boundary. Use canonical types, typed wrappers, or unknown with validation or narrowing. Check library defaults and inferred types: a passing type-check does not guarantee that any hasn't propagated into your code. For example, capture untyped JSON.parse and response .json() results as unknown; narrow or validate before accessing fields or passing to typed callers.
  • Type the captured value, not only its eventual result. A return annotation doesn't change the inferred types of parameters or destructured bindings. Capture untyped data as unknown, then narrow or validate before destructuring or accessing fields.
  • Mandatory type verification. Before finishing a TS/TSX change, run bun run type-check-pure. If TypeScript LSP tools are available, also inspect changed symbols with hover and go-to-definition; otherwise skip LSP check.

Type tightening

  • Avoid type casts and loose unknown — fix the signature instead.
  • If a function only needs one field of a wide object, accept that field — not the wide object. The cast often disappears once the signature is right.
  • Reach for Partial<T>, Pick<T, K>, Record<K, V>, and generics before reaching for a cast.
  • Match dictionary keys to the data. Use a finite key union when the keys are known. Open dictionaries can use an index signature, Record<string, T>, or Map; index signatures still constrain values, and changing their spelling to Record<string, T> does not make missing-key access safe.
  • Prefer making props/components generic (<T>) when a value flows through unchanged and the caller knows the type.
  • Prefer unknown over loose typing and narrow before use — an unknown value forces a guard at the point of use.
  • satisfies for object literals that must conform without widening (config objects, lookup maps, discriminated literals) — better than : T (widens) or as T (unsafe).
  • Avoid non-null assertions (!). Prefer a guard, early return, or ?.. Use ! only when non-nullness is provably true and localized, with a comment.
  • Guard indexed lookups that may miss. Arrays and dictionaries can return undefined even when the inferred type omits it. Use an iteration form that preserves the key/value relationship, and only assert keyof when the runtime keys are known to belong to the declared type.
  • No redundant runtime coercion — don't wrap already-typed values in Number() / String() / Boolean().
  • Type guards belong in frontend/src/metabase-types/guards/. Do not redefine them locally.
  • A cast you can't avoid needs a real justification comment. The metabase/no-unjustified-type-casts rule accepts any preceding comment — state the actual reason the cast is safe. NEVER write the legacy // Unjustified type cast. FIXME placeholder; it exists only on casts that predated the rule, and copying it sneaks an unjustified cast past the linter. If you can't articulate why the cast is correct, the cast is wrong — fix the types.
  • Keep unavoidable assertions local. Isolate a repeated or complex assertion behind a helper when that makes its invariant easier to enforce. Test nontrivial runtime assumptions that justify it; a trivial assertion does not automatically need a new helper or test. Do not weaken a public signature just to silence implementation errors.

Type modeling

  • Reuse existing types; don't re-declare them. Use canonical IDs and domain entity types from metabase-types/api (FieldId, TableId, ConcreteTableId, SchemaName, …) and key data structures by them (new Map<ConcreteTableId, …>()). Don't duplicate generated/API types — compose or derive (Pick, Omit, indexed access SomeType["field"], ReturnType). Search for the canonical declaration before introducing a local domain shape. If a type isn't exported directly, derive it from the owning function, endpoint, or hook rather than recreating its shape.
  • Generics must make promises the implementation can keep. A caller-selected get<T>(): T must not disguise an unchecked assertion about external data. Return unknown and validate, or accept a validator that establishes T. A factory such as function empty<T>(): T[] { return []; } is valid; judge the implementation, not how often T appears in the signature.
  • Prefer an honest type over false precision. Use generics when they express a real relationship. If a complex type cannot model the behaviour accurately, choose a simpler type or unknown with narrowing instead of asserting an unsupported guarantee.
  • Model the actual data contract; keep types narrow. Optional field?: T for a key that may be absent, field: T | undefined only when the key is always present but the value may be undefined, | null for explicit API nulls. Prefer domain unions over broad string / number / loose Record.
  • Refer to API implementation when defining or refining types to ensure they match the actual data structure. When considering a type cast, first consider if the type should be refined to match the actual data structure.
  • Optionality must reflect absence. Keep required fields required and optional fields optional. Normalise input when the application has a meaningful default, not merely to remove a type error. Preserve the actual wire shape in API types.
  • Represent related absence together when modelling internal state. If several fields exist or disappear together, consider a nullable containing object or a discriminated union. Do not reshape a raw API declaration unless the data actually has that shape.
  • Prefer explicit special states when designing a format. Use nullability or named union variants when sentinel values such as -1 hide meaning. Preserve established protocol sentinel values unless the behaviour is deliberately changed, or normalise them at an explicit boundary.
  • Discriminated unions for variant state, with exhaustive checks. Model "one of N shapes" as a union with a literal discriminant rather than a bag of optional fields, and exhaust it with ts-pattern's .exhaustive() so adding a variant becomes a compile error:
    import { match } from "ts-pattern";
    
    const result = match(status)
      .with({ type: "loading" }, () => <Spinner />)
      .with({ type: "error", error: P.select() }, (error) => <Error message={error.message} />)
      .with({ type: "success", data: P.select() }, (data) => <Content data={data} />)
      .exhaustive(); // Compile-time guarantee all cases handled
    
  • Derive union types from constants (as const + typeof/keyof) so the type and the values can't drift.
  • readonly / immutability where mutation isn't intended — component props, shared constants, exported config, and unmutated parameters. Prefer readonly T[] / ReadonlyArray<T> for inputs you don't mutate. Functions that mutate caller-owned data should make that behaviour explicit.
  • Construct complete, well-typed objects where practical. Prefer an object expression when it avoids partially initialised state or assertions. Incremental construction is fine when it is clearer and maintains the type's invariants.
  • Treat metabase-lib opaque types as black boxes. Use metabase-lib functions to work with types such as Lib.Query, rather than casting into their internal representation.
  • Type async and error states explicitly (a discriminated union or the data-layer's typed result) — never leave loading/error/empty implicit.

Function signatures

  • Make public contracts explicit where it improves stability and clarity. Annotate parameters and return types at shared boundaries when useful; let local values infer. Use satisfies or an annotation when a declaration needs an explicit shape check.
  • Accept the inputs the operation supports and return the most precise honest result. Narrow avoidable uncertainty inside the function, but preserve meaningful nullability and union variants in its return type.
  • Use named options when positional arguments are easy to confuse. Consecutive arguments with the same type are a useful warning sign, not an automatic requirement to rewrite a clear API.
  • Use async/await when it clarifies control flow or error handling. Returning an existing promise directly is also valid; a Promise return type alone does not require adding async.

Null and undefined

  • Narrow at the source. If a value is optional only in a corner case, don't thread undefined through every layer — guard at the producer.
  • Sensible defaults for optional values. Use ?. and ?? at the consumer.
  • Narrow nullable list elements when the operation requires present values. Filter with a type guard when missing entries should be discarded; preserve them when their absence or position carries meaning.
  • Avoid non-strict null comparisons (X != null) when X can never be null — use a strict check or narrow the type. Use checkNotNull where necessary.
  • Check actual nullability against API implementation. Find the API endpoint implementation and check if the field can actually be null.

Naming

  • Names describe the entity, not the mechanism. A name must reflect what the value holds.
  • Use domain vocabulary and include units where useful (timeoutMs, `wi

Content truncated.

When not to use it

  • →When introducing any types
  • →When using redundant runtime coercion
  • →When redefining local type guards

Prerequisites

TypeScript Language ServerProject type-check environment

Limitations

  • →No implicit any allowed
  • →Requires manual type-check execution
  • →Must use shared utility functions for reusability

How it compares

This workflow mandates strict type-safety and LSP verification for every change, rather than relying on loose inference or manual casting.

Compared to similar skills

typescript-write side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
typescript-write (this skill)305moReviewAdvanced
typescript08moNo flagsIntermediate
zustand1135moNo flagsIntermediate
dependency-upgrade268moReviewIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

Search skills

Search the agent skills registry