jwynia/agent-skills

Overview

This skill guides AI agents to produce and review high-quality TypeScript code using pragmatic best practices. It focuses on type safety, immutability, structured error handling, and maintainable code organization. Use it to shape code generation, refactoring, and design decisions that reduce runtime errors and improve developer ergonomics.

How this skill works

The skill inspects code and generates suggestions based on core principles: prefer unknown over any, favor readonly types, use explicit return types for public APIs, and adopt Result-style error handling. It provides module and function scaffolds, lint-style recommendations, and scripts for analysis, type generation, and scaffolding. The guidance is practical and applicable to new code, reviews, and JS-to-TS migrations.

When to use it

• Generating new TypeScript modules, services, or utilities.
• Reviewing TypeScript code for type-safety and maintainability issues.
• Refactoring JavaScript into TypeScript with strong typing.
• Designing public APIs, interfaces, or architecture patterns.
• Answering questions about generics, type guards, and advanced types.

Best practices

• Maximize compile-time checks: prefer unknown, avoid any, and declare explicit return types for exports.
• Make data immutable by default: use readonly properties and ReadonlyArray for inputs.
• Use typed error patterns: Result<T, E> unions and typed error classes over unchecked throws.
• Organize one concept per file, explicit named exports, and avoid wildcard barrel exports.
• Prefer interfaces for object shapes and type aliases for unions/intersections; document public types with JSDoc.

Example use cases

• Scaffold a new module with explicit types, constants, pure functions, and documentation.
• Convert a utility library from JavaScript to TypeScript, adding strict types and readonly contracts.
• Run a static analysis to flag usages of any, non-null assertions, and mutable API surfaces.
• Design an API client interface with clear config types, optional chaining, and typed Result returns.
• Refactor error handling to use Result unions and typed ValidationError classes for recoverable failures.