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
npx skills add martinholovsky/claude-skills-generator --skill typescript -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/typescript/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/typescript/
1Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill typescript -a codex2Manually: put the files in place
.agents/skills/typescript/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill typescript -a cursor2Manually: put the files in place
.cursor/skills/typescript/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install martinholovsky/claude-skills-generator skills/typescript2Manually: put the files in place
.github/skills/typescript/SKILL.md1Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill typescript -a gemini-cli2Platform CLI
gemini skills install https://github.com/martinholovsky/claude-skills-generator --path skills/typescriptManually: put the files in place
.devin/skills/typescript/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill typescript -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.