AGENT SKILL

typescript

Must always be enabled when writing/reviewing TypeScript code.

适用职业开发工程师
License 许可
MIT
最近更新
2026-11-01
Stars
★ 3
Forks
1

01 前言 Front Matter

name
typescript
description
Must always be enabled when writing/reviewing TypeScript code.

03 SKILL.md 正文

<philosophy>

Core Philosophy: Type-Level Verification

LLM-generated code faces inherent challenges with E2E testing and runtime verification. Compensate by maximizing compile-time verification through:

  • Algebraic data types (discriminated unions, exhaustive pattern matching)
  • Strict type constraints that make invalid states unrepresentable
  • Type-level proofs over runtime assertions

Goal: If it type-checks, it works. Shift as many bugs as possible from runtime to compile-time. </philosophy>

<type_assertions>

Type Assertions: Banned by Default

Rule: as Type Assertions are Prohibited

Rationale: Type assertions bypass TypeScript's type system and introduce type unsoundness. They are frequently misused to silence legitimate type errors.

Policy:

  • ❌ Never use as to resolve type errors
  • ❌ Never use as any or as unknown as X
  • ⚠️ Rare exceptions: Compiler limitations (e.g., specific generic inference bugs)
    • If you encounter such cases, leave the type error unresolved
    • Escalate to user with explanation: "Type error at path/to/file.ts:123 - requires manual review for potential as usage"

Why you cannot judge appropriately: As an LLM, you lack the contextual understanding to determine if a type assertion is truly necessary vs. masking a real type error. When in doubt, preserve type safety.

Alternative: Fix the Root Cause

Instead of as, address the underlying type issue:

  • Refine function signatures
  • Use type guards (if (typeof x === 'string'))
  • Employ discriminated unions
  • Add generic constraints </type_assertions>

<strict_typing>

Strict Typing Patterns

Prefer as const satisfies Over Loose Annotations

Problem with loose typing:

const config: Config = {
  mode: 'development',  // Type widened to string
  port: 3000
}
// config.mode is string, not 'development' | 'production'

Solution - strict typing with as const satisfies:

const config = {
  mode: 'development',
  port: 3000
} as const satisfies Config
// config.mode is exactly 'development' (literal type preserved)

Benefits:

  • Preserves literal types
  • Catches typos at definition site
  • Enables exhaustive checking in consumers
  • No type widening

Application:

  • Configuration objects
  • Constant lookup tables
  • Route definitions
  • Action type constants

Avoid Explicit Type Annotations When Inference Suffices

// ❌ Redundant annotation
const result: number = calculateTotal(items)

// ✅ Let TypeScript infer
const result = calculateTotal(items)

Use annotations when:

  • Constraining function parameters
  • Enforcing strict object shapes (as const satisfies)
  • Documenting public API boundaries </strict_typing>

<external_data>

External Data: Never Trust, Always Validate

Rule: No any for External Data

Sources requiring validation:

  • API responses (fetch, axios, etc.)
  • JSON.parse() results
  • LocalStorage/SessionStorage reads
  • FormData / user input
  • Environment variables
  • File system reads

Strategy 1: Type-Safe API Clients (Preferred)

Check for generated type definitions first:

  • Hono: hono/client with type inference
  • orval: OpenAPI-generated types and hooks
  • tRPC: End-to-end type safety
  • GraphQL Code Generator: Typed queries

Example (Hono client):

import { hc } from 'hono/client'
import type { AppType } from './server'

const client = hc<AppType>('/api')
const response = await client.users.$get()
// response is fully typed from server definition

Action: Review existing codebase for established patterns. Most projects already have type-safe API layers.

Strategy 2: Runtime Validation Libraries

When type generation is unavailable, use schema validation:

Preference order:

  1. Existing project dependency (check package.json)
  2. valibot (lightweight, install if needed: pnpm add valibot)
  3. zod (popular, larger bundle)

Example (valibot):

import * as v from 'valibot'

const UserSchema = v.object({
  id: v.number(),
  name: v.string(),
  role: v.union([v.literal('admin'), v.literal('user')])
})

// Parse and validate
const response = await fetch('/api/user')
const data = await response.json()
const user = v.parse(UserSchema, data)  // Throws if invalid
// user is now typed as { id: number, name: string, role: 'admin' | 'user' }

Example (JSON.parse):

// ❌ Unsafe
const data = JSON.parse(localStorage.getItem('config')!)

// ✅ Validated
const raw = localStorage.getItem('config')
if (raw) {
  const data = v.parse(ConfigSchema, JSON.parse(raw))
}

Never Skip Validation

Even if "you know" the shape, external data can change:

  • API contracts evolve
  • Users manipulate localStorage
  • Third-party services have bugs

Type safety = static types + runtime validation </external_data>

<best_practices>

General Best Practices

Prefer Arrow Functions Over Function Declarations

Rule: Use arrow functions (=>) instead of function keyword for consistency and lexical scoping benefits.

Rationale:

  • Consistent lexical this binding (no context confusion)
  • More concise syntax
  • Better integration with modern TypeScript patterns
  • Prevents accidental hoisting-related bugs
// ❌ Function declaration
function calculateTotal(items: Item[]): number {
  return items.reduce((sum, item) => sum + item.price, 0)
}

// ✅ Arrow function
const calculateTotal = (items: Item[]): number => {
  return items.reduce((sum, item) => sum + item.price, 0)
}

// ✅ Concise form (single expression)
const calculateTotal = (items: Item[]): number =>
  items.reduce((sum, item) => sum + item.price, 0)

Exception: When hoisting is genuinely required (rare), document the reason.

Discriminated Unions for State

type LoadingState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error }

const render = (state: LoadingState<User>) => {
  switch (state.status) {
    case 'idle':
      return 'Not started'
    case 'loading':
      return 'Loading...'
    case 'success':
      return state.data.name  // data is available
    case 'error':
      return state.error.message  // error is available
  }
}

Benefits: Impossible to access data when status is 'error'.

Exhaustiveness Checking

const assertNever = (x: never): never => {
  throw new Error(`Unexpected value: ${x}`)
}

switch (state.status) {
  case 'idle':
  case 'loading':
  case 'success':
  case 'error':
    return
  default:
    assertNever(state)  // Compile error if cases are missing
}

Avoid Optional Properties for State

// ❌ Ambiguous state
type User = {
  data?: UserData
  error?: Error
}
// What if both are defined? Neither?

// ✅ Explicit state
type User =
  | { status: 'success'; data: UserData }
  | { status: 'error'; error: Error }

Use unknown Over any for Truly Unknown Types

// ❌ Disables all type checking
const process = (data: any) => {
  return data.foo.bar  // No errors, runtime explosion
}

// ✅ Forces validation
const process = (data: unknown) => {
  if (typeof data === 'object' && data !== null && 'foo' in data) {
    // Narrow the type before use
  }
}

Readonly by Default

// Prevent accidental mutations
type Config = {
  readonly apiUrl: string
  readonly timeout: number
}

// For arrays
const items = ['a', 'b'] as const

Avoid Type-Level Gymnastics

If type definitions become incomprehensible, simplify the design:

  • Complex conditional types often indicate over-abstraction
  • Prefer explicit discriminated unions over heavily generic types
  • Maintainability > cleverness </best_practices>

<error_handling>

When Type Errors Cannot Be Resolved

If you encounter legitimate type errors you cannot fix without as:

  1. Leave the error in place
  2. Document the issue:
    // TODO: Type error at line X - potential TypeScript limitation
    // Requires manual review before using type assertion
    const result = someComplexOperation()  // Type error here
    
  3. Notify the user: "Type error remains at src/module.ts:45 - escalated for review"

Do not:

  • Silently add as assertions
  • Use any to bypass the error
  • Restructure correct code to satisfy incorrect types </error_handling>

04 同仓库更多 Skills

shengdabai
shengdabai/Tony-Claude-Code-Skills

seedance-prompt-en

Write effective prompts for Jimeng Seedance 2.0 multimodal AI video generation. Use when users want to create video prompts using text, images, videos, and audio inputs with the @ reference system. Covers camera movements, effects replication, video extension, editing, music beat-matching, e-commerce ads, short dramas, and educational content.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

onepage-pdf

Convert an HTML page into a single continuous-page PDF (one tall page, no pagination breaks), preserving desktop layout, backgrounds and selectable text. Use when the user asks to turn an HTML file/report/proposal into a "single-page PDF", "long PDF", "不分页 PDF", "单页 PDF", "长图式 PDF", or complains that an HTML-to-PDF export breaks into pages or cuts content. Supports optional string redaction with leak verification.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

native-feel-cross-platform-desktop

Use when the user is designing, prototyping, or rewriting a desktop app that must run on multiple OSes (macOS + Windows, optionally Linux) AND feel indistinguishable from a native app to its users — fast launch, native windowing, native input handling, native materials. Trigger words include "cross-platform desktop", "Electron alternative", "Tauri vs native", "WebView wrapper", "near-native performance", "Raycast architecture", "WebKit/WebView2 quirks", "WKWebView", "system tray app", "global hotkey app", "launcher app". Do NOT trigger this skill for pure web apps, pure mobile apps, or for greenfield projects that have no native-feel requirement.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

gstack

Router for the gstack skill suite. (gstack)

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

fireworks-tech-graph

Use when the user wants to create any technical diagram - architecture, data flow, flowchart, sequence, agent/memory, or concept map - and export as SVG+PNG. Trigger on: "画图" "帮我画" "生成图" "做个图" "架构图" "流程图" "可视化一下" "出图" "generate diagram" "draw diagram" "visualize" or any system/flow description the user wants illustrated.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

dbs-video-extract

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

★ 3