Discriminated Unions: A TypeScript Agent Skill Worth Adding

Where this fits

You are refactoring a React component that renders different forms based on a status field. The current code has optional error, data, and loading props, and every render checks if (error !== undefined && data === undefined). This pattern breeds bugs and makes state transitions hard to reason about. The discriminated-unions skill steps in when you need to model mutually exclusive variants—like state machines, API responses, or polymorphic props—with TypeScript's type system as your safety net. It applies, reviews, and explains the exact TypeScript Style Guide conventions, so you stop fighting invalid states and start letting the compiler do the heavy lifting.

Why agents benefit

• Detects misuse instantly: The agent recognizes when a discriminated union is the right model versus cases where optional properties or simple value changes are more appropriate.
• Enforces exhaustiveness: It checks that your switch or if/else chains cover every variant, eliminating the dreaded "silent fallthrough" bug.
• Applies conventions contextually: It inspects your repository's existing style and ESLint rules, then adapts the guidance rather than forcing a generic template.
• Explains tradeoffs: When a discriminated union isn't clearly the best fit, the agent articulates why, using concrete examples from your codebase.
• Stays on scope: It never drifts into unrelated TypeScript style rules—just the discriminated-union conventions relevant to your task.

Practical scenarios

Modeling application state with a single source of truth

Your app has a Status type that can be 'idle' | 'loading' | 'success' | 'error'. Without a discriminated union, you carry data, error, and isLoading as independent booleans, leading to impossible states like isLoading && error. The agent refactors to a union like { status: 'loading' } | { status: 'success'; data: User } | { status: 'error'; error: Error }, and every component only accesses data when status === 'success'.

Handling React props with variant-specific fields

A modal component accepts type: 'info' | 'warning' but also optional severity and icon. The agent identifies that severity and icon only make sense for 'warning'. It converts the props into a discriminated union, so consumers can't accidentally pass severity to an 'info' modal.

Exhaustiveness checking in API response handling

You have a fetch function that returns either { ok: true; data: T } or { ok: false; error: string }. The agent adds a default branch with assertNever to ensure every future variant is handled explicitly, catching missing cases during development.

Add it to your agent workflow

Install the skill with a single command:

npx skills add mkosir/typescript-style-guide --skill discriminated-unions

Then, when you describe a task like "review the state model for the checkout flow and suggest improvements", the agent automatically applies the discriminated-union guidance and points out places where the current optional-property approach is error-prone.

Compare before adopting

Before you add this skill to your toolkit, compare it against your current practices. Look at how your team already handles mutually exclusive states—do you rely on runtime checks or do you already use unions? Check if the skill's conventions align with your existing ESLint and TypeScript configuration. Also consider alternative patterns like enums with optional fields or union types without a common discriminant. The skill's README explicitly says it respects your repo's conventions, so it's low-risk to try.

Why it is worth tracking

The discriminated-unions skill comes from a well-maintained TypeScript style guide with 780 stars, indicating community trust and active upkeep. Quality signals include its narrow scope, clear boundaries, and emphasis on repository-specific conventions. It's a strong candidate for agents that need to produce idiomatic, type-safe TypeScript. Evaluate it when you're building agents that refactor React components, manage complex state, or enforce type rigor in API layers. You can also explore related skills from the same guide through the OpenAgentSkill directory for a broader TypeScript-specific toolkit.