Skip to main content
skill CX Codex

typescript · martinholovsky — Claude Code skill: what it does, how to install

Enforces strict TypeScript conventions, Zod schema validation, and test-driven development in your coding agent.

Unlicense 213 installs ★ 48 updated 2025-12-06

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add martinholovsky/claude-skills-generator --skill typescript -a claude-code
Open on GitHub

What typescript does

This skill guides the assistant through strict typing rules tailored for TypeScript 5.3.0 and newer. It rejects any in favor of unknown paired with custom type guards. Data structures stay immutable by default via readonly modifiers, while module boundaries require explicit type definitions for inputs and outputs.

Included patterns cover branded types like UserId to avoid identifier confusion, alongside discriminated unions for state machines. Runtime validation relies on Zod 3.22.0. The workflow strictly adheres to TDD, prompting tests in Vitest before code implementation. Without strict: true and noUncheckedIndexedAccess enabled in tsconfig.json, the compiler will miss the intended guarantees.

What it helps with

  • validate untrusted inputs using Zod schemas
  • avoid accidental ID confusion with branded types
  • model state machines using discriminated unions
  • configure strict compiler options in tsconfig.json
  • generate Vitest unit tests before writing business logic

Example prompts for the agent

  • Create a Zod schema for incoming command payloads and infer the type
  • Build a branded type for UserId with a runtime regex validator
  • Set up a state machine using a discriminated union with an exhaustive switch

How to install typescript

1Skills CLI (Vercel)

npx skills add martinholovsky/claude-skills-generator --skill typescript -a claude-code

2Manually: put the files in place

~/.claude/skills/typescript/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/typescript/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about typescript

How to install typescript in Claude Code?

Run npx skills add martinholovsky/claude-skills-generator --skill typescript -a claude-code in your terminal. This saves the skill file at ~/.claude/skills/typescript/SKILL.md.

What does the typescript skill do?

It instructs the coding assistant to apply strict compiler rules, replace any with unknown, enforce Zod validation, and write Vitest tests first.

Which library versions are expected?

The configuration targets typescript version ^5.3.0, zod version ^3.22.0, and @types/node version ^20.0.0.

Source text

SKILL.md · Unlicense
---
name: typescript
description: Type-safe development patterns for JARVIS AI Assistant
model: sonnet
risk_level: MEDIUM
version: 1.0.0
---

# TypeScript Development Skill

> **File Organization**: This skill uses split structure. See `references/` for advanced patterns and security examples.

## 1. Overview

This skill provides TypeScript expertise for the JARVIS AI Assistant, ensuring type safety across the entire codebase including Vue components, API routes, 3D rendering, and state management.

**Risk Level**: MEDIUM - Type system prevents runtime errors, enforces contracts, but misconfiguration can lead to security gaps

**Primary Use Cases**:
- Defining type-safe interfaces for JARVIS system data
- Runtime validation with Zod schemas
- Generic patterns for reusable HUD components
- Strict null checking to prevent crashes

## 2. Core Responsibilities

### 2.1 Fundamental Principles

1. **TDD First**: Write tests before implementation - red, green, refactor
2. **Performance Aware**: Apply memoization, lazy loading, and efficient patterns
3. **Strict Mode Always**: Enable all strict compiler options - no shortcuts
4. **Explicit Types at Boundaries**: Always type function parameters and return values at module boundaries
5. **Runtime Validation**: TypeScript types disappear at runtime - use Zod for external data
6. **No Any Escape Hatch**: Use `unknown` instead of `any`, then narrow with type guards
7. **Immutable by Default**: Prefer `readonly` and `as const` for data integrity
8. **Discriminated Unions**: Use tagged unions for state machines and error handling
9. **Branded Types**: Create nominal types for IDs and sensitive values

## 3. Technology Stack & Versions

### 3.1 Recommended Versions

| Package | Version | Security Notes |
|---------|---------|----------------|
| typescript | ^5.3.0 | Latest stable with improved type inference |
| zod | ^3.22.0 | Runtime validation, schema-first |
| @types/node | ^20.0.0 | Match Node.js version |

### 3.2 Compiler Configuration

```json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "exactOptionalPropertyTypes": true,
    "noPropertyAccessFromIndexSignature": true,
    "forceConsistentCasingInFileNames": true,
    "verbatimModuleSyntax": true,
    "moduleResolution": "bundler",
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"]
  }
}
```

## 4. Implementation Patterns

### 4.1 Branded Types for Security

```typescript
// types/branded.ts
declare const __brand: unique symbol

type Brand<T, B> = T & { [__brand]: B }

// ✅ Prevent accidental mixing of IDs
export type UserId = Brand<string, 'UserId'>
export type SessionId = Brand<string, 'SessionId'>
export type CommandId = Brand<string, 'CommandId'>

// Factory functions with validation
export function createUserId(id: string): UserId {
  if (!/^usr_[a-zA-Z0-9]{16}$/.test(id)) {
    throw new Error('Invalid user ID format')
  }
  return id as UserId
}

// ✅ Type system prevents mixing IDs
function getUser(id: UserId): User { /* ... */ }
function getSession(id: SessionId): Session { /* ... */ }

// This won't compile:
// getUser(sessionId) // Error: SessionId not assignable to UserId
```

### 4.2 Discriminated Unions for State

```typescript
// types/jarvis-state.ts

// ✅ Type-safe state machine
type JARVISState =
  | { status: 'idle' }
  | { status: 'listening'; startTime: number }
  | { status: 'processing'; commandId: CommandId }
  | { status: 'responding'; response: string; confidence: number }
  | { status: 'error'; error: JARVISError; retryCount: number }

// ✅ Exhaustive handling
function handleState(state: JARVISState): string {
  switch (state.status) {
    case 'idle':
      return 'Ready'
    case 'listening':
      return `Listening for ${Date.now() - state.startTime}ms`
    case 'processing':
      return `Processing ${state.commandId}`
    case 'responding':
      return `${state.response} (${state.confidence}%)`
    case 'error':
      return `Error: ${state.error.message}`
    default:
      // ✅ Compile-time exhaustiveness check
      const _exhaustive: never = state
      return _exhaustive
  }
}
```

### 4.3 Runtime Validation with Zod

```typescript
// schemas/command.ts
import { z } from 'zod'

// ✅ Schema-first approach
export const commandSchema = z.object({
  id: z.string().regex(/^cmd_[a-zA-Z0-9]{16}$/),
  action: z.enum(['navigate', 'control', 'query', 'configure']),
  target: z.string().min(1).max(100),
  parameters: z.record(z.unknown()).optional(),
  timestamp: z.number().int().positive(),
  priority: z.number().min(0).max(10).default(5)
})

// ✅ Infer TypeScript type from schema
export type Command = z.infer<typeof commandSchema>

// ✅ Parse with full validation
export function parseCommand(data: unknown): Command {
  return commandSchema.parse(data)
}

// ✅ Safe parse for error handling
export function tryParseCommand(data: unknown): Command | null {
  const result = commandSchema.safeParse(data)
  return result.success ? result.data : null
}
```

### 4.4 Generic Patterns for HUD Components

```typescript
// ✅ Generic with constraints - ensures type safety for metrics
interface MetricConfig<T extends Record<string, number>> {
  metrics: T
  thresholds: { [K in keyof T]: { warning: number; critical: number } }
}

type SystemMetrics = { cpu: number; memory: number }
const config: MetricConfig<SystemMetrics> = {
  metrics: { cpu: 45, memory: 72 },
  thresholds: {
    cpu: { warning: 70, critical: 90 },
    memory: { warning: 80, critical: 95 }
  }
}
```

### 4.5 Type Guards for Narrowing

```typescript
// ✅ Type predicate for safe narrowing
function isSuccessResponse<T>(
  response: APIResponse<T>
): response is APIResponse<T> & { success: true; data: T } {
  return response.success && response.data !== undefined
}

// Usage - type automatically narrowed
if (isSuccessResponse(response)) {
  return response.data // ✅ Type is T, not T | undefined
}
```

### 4.6 Utility Types for JARVIS

```typescript
// types/utilities.ts

// ✅ Deep readonly for immutable state
type DeepReadonly<T> = {
  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K]
}

// ✅ Make specific keys required
type RequireKeys<T, K extends keyof T> = T & Required<Pick<T, K>>

// ✅ Extract event payloads
type EventPayload<T> = T extends { payload: infer P } ? P : never

// ✅ Async function return type
type AsyncReturnType<T extends (...args: any[]) => Promise<any>> =
  T extends (...args: any[]) => Promise<infer R> ? R : never
```

## 5. Implementation Workflow (TDD)

### Step 1: Write Failing Test First

```typescript
// tests/utils/command-parser.test.ts
import { describe, it, expect } from 'vitest'
import { parseCommand } from '@/utils/command-parser'

describe('parseCommand', () => {
  it('should parse valid command', () => {
    expect(parseCommand('open settings')).toEqual({
      action: 'open', target: 'settings', parameters: {}
    })
  })

  it('should extract parameters', () => {
    expect(parseCommand('set volume to 80')).toEqual({
      action: 'set', target: 'volume', parameters: { value: 80 }
    })
  })

  it('should throw on empty command', () => {
    expect(() => parseCommand('')).toThrow('Command cannot be empty')
  })
})
```

### Step 2: Implement Minimum to Pass

Write only code needed to make tests green.

### Step 3: Refactor if Needed

Improve code quality while keeping tests green.

### Step 4: Run Full Verification

```bash
npx vitest run              # Unit tests
npx eslint . --ext .ts,.tsx # Linting
npx tsc --noEmit            # Type checking
```

## 6. Performance Patterns

### 6.1 Memoization

```typescript
// ❌ BAD - Recalculates on every render
const processed = data.map(item => heavyTransform(item))

// ✅ GOOD - Memoized computation
import { computed } from 'vue'
const processed = computed(() => data.value.map(item => heavyTransform(item)))
```

### 6.2 Lazy Loading

```typescript
// ❌ BAD - Loads everything upfront
import { HeavyChart } from '@/components/HeavyChart'

// ✅ GOOD - Lazy load heavy components
import { defineAsyncComponent } from 'vue'
const HeavyChart = defineAsyncComponent(() => import('@/components/HeavyChart'))
```

### 6.3 Debounce/Throttle

```typescript
// ❌ BAD - API call on every keystroke
const handleSearch = (q: string) => fetchResults(q)

// ✅ GOOD - Debounced search (300ms delay)
import { useDebounceFn } from '@vueuse/core'
const debouncedSearch = useDebounceFn((q: string) => fetchResults(q), 300)
```

### 6.4 Efficient Data Structures

```typescript
// ❌ BAD - O(n) lookup
const user = users.find(u => u.id === id)

// ✅ GOOD - O(1) lookup with Map
const userMap = new Map(users.map(u => [u.id, u]))
const user = userMap.get(id)

// ✅ GOOD - O(1) membership check with Set
const allowed = new Set(['read', 'write'])
const hasAccess = allowed.has(permission)
```

### 6.5 Parallel Async Operations

```typescript
// ❌ BAD - Sequential (total = sum of times)
const user = await fetchUser()
const metrics = await fetchMetrics()

// ✅ GOOD - Parallel (total = max of times)
const [user, metrics] = await Promise.all([fetchUser(), fetchMetrics()])

// ✅ GOOD - With error handling
const results = await Promise.allSettled([fetchUser(), fetchMetrics()])
```

## 7. Security Standards

### 7.1 Known Vulnerabilities

TypeScript itself has a strong security record. Main risks come from:

| Risk Area | Description | Mitigation |
|-----------|-------------|------------|
| Type Erasure | Types don't exist at runtime | Use Zod for external data validation |
| Any Type | Disables type checking | Enable noImplicitAny, use unknown |
| Type Assertions | Can bypass type system | Avoid `as`, use type guards instead |

### 7.2 OWASP Top 10 Coverage

| OWASP Category | TypeScript Mitigation |
|----------------|----------------------|
| A03 Injection | Typed APIs prevent string interpolation in queries |
| A04 Insecure Design | Strong typing enforces secure interfaces |
| A08 Software Integrity | Compile-time checks catch errors before deployment |

### 7.3 Secure Type Patterns

```typescript
// ❌ DANGEROUS - Type assertion bypasses safety
const userData = apiResponse as User

// ✅ SECURE - Runtime validation
const userData = userSchema.parse(apiResponse)

// ❌ DANGEROUS - any disables all checks
function process(data: any) { /* ... */ }

// ✅ SECURE - unknown requires narrowing
function process(data: unknown) {
  const validated = commandSchema.parse(data)
  // Now safely typed
}
```

## 8. Testing & Quality

```typescript
// Type testing with vitest
import { expectTypeOf } from 'vitest'

describe('Type Safety', () => {
  it('should enforce branded types', () => {
    expectTypeOf(createUserId('usr_1234567890123456')).toEqualTypeOf<UserId>()
  })
})

// Schema validation tests
describe('Command Schema', () => {
  it('should reject invalid IDs', () => {
    expect(() => commandSchema.parse({ id: 'invalid' })).toThrow()
  })

  it('should accept valid commands', () => {
    const result = commandSchema.parse({ id: 'cmd_1234567890123456', action: 'query' })
    expect(result.action).toBe('query')
  })
})
```

## 9. Common Mistakes & Anti-Patterns

### 9.1 Critical Security Anti-Patterns

#### Never: Use Type Assertions for External Data

```typescript
// ❌ DANGEROUS - No runtime validation
const user = JSON.parse(data) as User

// ✅ SECURE - Validate at runtime
const user = userSchema.parse(JSON.parse(data))
```

#### Never: Ignore Null/Undefined Checks

```typescript
// ❌ DANGEROUS - Runtime crash if undefined
function getConfig(key: string) {
  return config[key].value  // May be undefined!
}

// ✅ SECURE - Explicit null handling
function getConfig(key: string): string | undefined {
  return config[key]?.value
}
```

#### Never: Use Index Signatures Without Checks

```typescript
// ❌ DANGEROUS - No type safety
const handlers: Record<string, Handler> = {}
handlers['cmd'].execute()  // May be undefined!

// ✅ SECURE - Explicit lookup with check
const handler = handlers['cmd']
if (handler) {
  handler.execute()
}
```

### 9.2 Performance Anti-Patterns

#### Avoid: Excessive Type Complexity

```typescript
// ❌ BAD - Unreadable, slow compilation
type DeepPartialRecord<T> = T extends object
  ? { [K in keyof T]?: DeepPartialRecord<T[K]> }
  : T extends Array<infer U>
  ? Array<DeepPartialRecord<U>>
  : T

// ✅ GOOD - Simple, clear types
interface PartialConfig {
  theme?: Partial<ThemeConfig>
  metrics?: Partial<MetricsConfig>
}
```

## 10. Pre-Deployment Checklist

### Phase 1: Before Writing Code

- [ ] Write failing tests first (TDD)
- [ ] Define types and interfaces for new features
- [ ] Plan Zod schemas for external data
- [ ] Identify performance-critical paths
- [ ] Review existing patterns in codebase

### Phase 2: During Implementation

- [ ] `strict: true` enabled in tsconfig
- [ ] `noUncheckedIndexedAccess: true` enabled
- [ ] `noImplicitAny: true` enabled
- [ ] No `any` types in production code
- [ ] All external data validated with Zod
- [ ] Branded types for sensitive IDs
- [ ] Discriminated unions for state machines
- [ ] Memoization applied to expensive computations
- [ ] Lazy loading for heavy components
- [ ] Efficient data structures (Map/Set) for lookups

### Phase 3: Before Committing

- [ ] All tests pass (`npx vitest run`)
- [ ] No linting errors (`npx eslint .`)
- [ ] No TypeScript errors (`npx tsc --noEmit`)
- [ ] All API inputs validated at runtime
- [ ] No type assertions on external data
- [ ] Performance patterns applied where needed

## 11. Summary

TypeScript provides compile-time safety for JARVIS development:

1. **Strict Configuration**: Enable all strict options for maximum safety
2. **Runtime Validation**: Types disappear at runtime - use Zod
3. **Branded Types**: Prevent mixing of IDs and sensitive values
4. **Type Guards**: Safely narrow `unknown` data with predicates

**Remember**: TypeScript only checks at compile time. Every boundary with external data must have runtime validation.

---

**References**:
- `references/advanced-patterns.md` - Complex type patterns
- `references/security-examples.md` - Secure typing practices

© martinholovsky · Unlicense · martinholovsky/claude-skills-generator

Similar skills

All skills for Programming languages →

typescript by other authors comes first.

typescript gentleman-programming Enforces strict TypeScript rules: const types, flat interfaces, type guards. Kicks in when the agent writes types, interfaces, or generics. CX Codex +1 500installs typescript PyModel This skill for Claude Code provides guidance on TypeScript 7 types and configuration. Ask the agent to apply it while editing tsconfig.json, async code, or module imports. CX Codex +1 657installs typescript alinaqi Skill for TypeScript work across Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. Configures strict mode, type checking via eslint and jest, pre-commit hooks to catch errors early. CX Codex +1 320installs typescript Mindrally Enforces strict TypeScript standards and functional code patterns in your AI assistant. It bans any, replaces enums with maps, and caps function length at 20 lines. CX Codex +1 1,000installs typescript sentimony typescript guides coding agents through compiler errors, strict flags, and tsconfig setups across monorepos and web frameworks. Useful for tricky typing issues. CX Codex +1 5,200installs typescript-node-stinger Legion Code Inc. The typescript-node-stinger skill reviews TypeScript and Node code, including SvelteKit typing, project settings, tests, and npm package builds. Use it for focused code checks. CX Codex +1 ★ 96repo stars TypeScript Library taste f TypeScript Library taste is a ChatGPT prompt for setting build and release conventions for TypeScript libraries. It covers tests, package exports, and versioning. GP ChatGPT ★ 178,201repo stars gravitas-typescript udaysharmadev gravitas-typescript is a Claude Code skill that enforces strict TypeScript checks, sets up tests with Vitest or Jest, and blocks unsafe as casts. CX Codex +1 439installs typescript-clean-code bmad-labs typescript-clean-code — a skill for reviewing and refactoring TypeScript: code smell catalogs, four detection layers, and step-by-step workflows. CX Codex +1 669installs typescript-node-wasp-drone Legion Code Inc. typescript-node-wasp-drone reviews TypeScript and Node.js projects built as SvelteKit apps on Vercel or npm libraries and CLIs. Use it for typing, validation, tests, and project tooling. CX Codex ★ 96repo stars typescript-mcp-server-generator official github typescript-mcp-server-generator generates a TypeScript MCP server project with tools, resources, and configuration. Use it when a new server should start on the MCP TypeScript SDK v2. CX Codex +1 12,050installs

From the same set50

The whole set →
python A backend skill for Python work: type hints, asyncio, input validation and pytest. The agent writes the failing test before the code. CX Codex +1 229installs prompt-engineering prompt-engineering is a Claude Code skill with rules and patterns for secure prompt building, injection defense, and LLM response validation. CX Codex +1 228installs graphql-expert graphql-expert is a Claude Code skill for designing GraphQL schemas, building resolvers, and working with federation. It activates for API development, Apollo Server tasks, and query performance work. CX Codex +1 220installs SQLCipher Encrypted Database Expert The SQLCipher Encrypted Database Expert skill guides SQLCipher database work, from key handling and rotation to SQLite migrations. Use it when building applications that store sensitive data locally. CX Codex +1 216installs async-expert async-expert guides AI coding agents through async development in Python, JS, C#, and Rust using TDD and API verification. CX Codex +1 212installs Cross-Platform Build Expert Cross-Platform Build Expert guides desktop application packaging for Windows, macOS, and Linux, focusing on Tauri setups, code signing, and CI/CD pipelines. CX Codex +1 210installs cloud-api-integration cloud-api-integration is a Claude Code skill for building cloud AI API integrations. It covers clients for Claude, GPT-4, and Gemini, including request security and provider fallback. CX Codex +1 203installs harbor-expert harbor-expert — a skill that turns the agent into a Harbor registry admin: Trivy scans on push, Notary v2 and Cosign signing, project RBAC and multi-region replication. CX Codex +1 200installs

Project sponsors

Companies that keep this analytics open