agentleFS
HQarroumHQarroum/writing-typescript/SKILL.md

typescript-style

Skill1 starsChanged 9 months agoMITView on GitHub

Enforces TypeScript coding standards including naming, code structure, type safety, error handling, and project setup. Use when writing, reviewing, or refactoring TS files, or initializing new TS projects.

  • Reads credentials

3 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions3 projects use a version of this.

    Word for word · 1

    1. HQarroum/typescript-skill★ 1100% same

    Edited · 0

    None found.

    Wrote their own version · 2

    1. tjx666/vscode-mcp★ 100same name
    2. RichardMcQuiston01/unofficial-claude-skill-examples★ 1same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

The file

Show its rules and text

We split this skill into the rules it gives an agent

47 rules. About 0 are common, 24 are distinctive, and 23 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈24

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 23

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use simple variable and function names const user = getUser().

    line 20
  2. Very specific:

    When the type is genuinely unknown at compile time, use unknown and narrow via type guards.

    line 25
  3. Very specific:

    Prefer satisfies over as, validates the type at the assignment site while preserving the narrower inferred type.

    line 27
  4. Very specific:

    Use readonly for properties that are never reassigned after construction.

    line 28
  5. Very specific:

    Use as const for literal objects and arrays that should not change.

    line 29
  6. Very specific:

    Use import type when importing symbols used only as types.

    line 30
  7. Very specific:

    Use const by default. Use let only when reassignment is required.

    line 40
  8. Very specific:

    Only === and !== for comparisons.

    line 41
  9. Distinctive:

    Use engine-specific protocols for module imports:

    line 83
  10. Very specific:

    Prefer async/await over .then() chains.

    line 91
  11. Distinctive:

    Use early returns to reduce nesting.

    line 92
  12. Distinctive:

    Keep functions small and focused.

    line 93
  13. Very specific:

    Use higher-order functions (map, filter, reduce) over imperative loops.

    line 94
  14. Distinctive:

    Use one variable per declaration statement.

    line 95
  15. Very specific:

    Prefer for...of when iterating objects.

    line 96
  16. Distinctive:

    Prefer simple, concise code.

    line 97
  17. Distinctive:

    No default exports, always use named exports.

    line 98
  18. Distinctive:

    Use discriminated unions over optional properties for more complex types.

    line 99
  19. Very specific:

    When using declarative code, for example, using Zod or Drizzle schemas, write the declarative code by formatting it with each property or …

    line 113
  20. Very specific:

    Prefer TypeScript type over enum.

    line 153
  21. Distinctive:

    When chaining multiple function calls using a fluent interface:

    line 169
  22. Distinctive:

    When defining object literals, format the code with each property on a new line.

    line 180
  23. Distinctive:

    Always use curly braces for blocks.

    line 192
  24. Distinctive:

    Avoid global type augmentation when possible.

    line 214
  25. Distinctive:

    Use JSDoc comments for functions, types, enums, classes, methods, and class properties.

    line 219
  26. Very specific:

    Only use @type in JSDoc comments when the type or unit is non-obvious.

    line 277
  27. Very specific:

    Do not use decorative separators (e.g., -, // --------, // ========) in comments.

    line 287
  28. Distinctive:

    Use inline comments to explain *what* the code is doing and *why*.

    line 289
  29. Distinctive:

    Do not comment the top of files with a description of the file's purpose.

    line 317
  30. Very specific:

    Do not use single-line block comments (/ ...

    line 318
  31. Distinctive:

    Use multi-line comments for global variables or constants.

    line 322
  32. Very specific:

    Prefer Map and Set over plain objects for frequent lookups.

    line 334
  33. Distinctive:

    Avoid unnecessary spread copies in hot paths.

    line 335
  34. Very specific:

    Use Promise.all() for independent async operations.

    line 336
  35. Distinctive:

    No deep nesting of callbacks or conditionals.

    line 343
  36. Very specific:

    Avoid non-null assertions (!).

    line 344
  37. Distinctive:

    No over-annotation of inferred types when not necessary.

    line 345
  38. Distinctive:

    Avoid Barrel files as they break tree-shaking, slow down bundlers and IDE indexing, create circular dependency traps, and inflate bundle …

    line 346
  39. Distinctive:

    No nested ternaries — max one level deep.

    line 348
  40. Distinctive:

    No magic numbers / strings — extract to named constants.

    line 349
  41. Distinctive:

    No unbounded or user-supplied regular expressions — avoid catastrophic backtracking (ReDoS).

    line 351
  42. Very specific:

    Use vitest for unit and integration testing.

    line 367
  43. Distinctive:

    Use supertest for HTTP endpoint testing when a headless browser is not needed.

    line 368
  44. Very specific:

    Write tests per feature or component in a dedicated tests/ directory within each associated package.

    line 369
  45. Very specific:

    Use z.infer<typeof Schema> to derive types from Zod schemas.

    line 481
  46. Very specific:

    Use .describe() to add descriptions to schema properties.

    line 482
  47. Distinctive:

    Add the following files to your project.

    line 494

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

TypeScript Code Guidelines

Naming Conventions

  • Files and directories: kebab-case.ts.
  • Classes, interfaces, types, enums: PascalCase.
  • Functions, variables, methods: camelCase.
  • Constants: UPPER_SNAKE_CASE.
  • Booleans: prefix with is, has.
  • Functions: start with, or consist of, a verb (get, resolve, create).
  • Use simple variable and function names const user = getUser().

Type Safety

  • No any.
  • When the type is genuinely unknown at compile time, use unknown and narrow via type guards.
  • Omit explicit return types when TypeScript can infer them unambiguously.
  • Prefer satisfies over as, validates the type at the assignment site while preserving the narrower inferred type.
  • Use readonly for properties that are never reassigned after construction.
  • Use as const for literal objects and arrays that should not change.
  • Use import type when importing symbols used only as types.

Code Style

Syntax

  • 2 spaces for indentation.
  • Single quotes for strings.
  • Template literals for multi-line strings and interpolation.
  • Arrow functions for functions and callbacks.
  • Use const by default. Use let only when reassignment is required. No var.
  • Only === and !== for comparisons.
  • Parentheses around return values (Opinionated):
  • Variable declarations at the top of their scope.
const work = () => {
  const x = 1;
  const y = 2;

  // Do work.

  return (x + y);
};

Imports

  • Use ES modules.
  • Group imports in the following order:
    1. Built-in modules (e.g. fs, path)
    2. External libraries (e.g. react, lodash)
    3. Internal modules (e.g. ./utils, ../components/Button)
    4. Type imports (e.g. import type { User } from './types')
    5. Multiple imports.
import { readFile } from 'node:fs';
import { useState } from 'react';
import { debounce } from 'lodash';
import type { Request, Response } from 'express';
import type { Client } from './sdk';

import {
  orderByDate,
  orderByPrice
} from './components/orders';
import {
  User,
  Product
} from './models';
  • Use engine-specific protocols for module imports:
import { readFile } from 'node:fs';

Structure

  • Prefer async/await over .then() chains.
  • Use early returns to reduce nesting.
  • Keep functions small and focused.
  • Use higher-order functions (map, filter, reduce) over imperative loops.
  • Use one variable per declaration statement.
  • Prefer for...of when iterating objects.
  • Prefer simple, concise code.
  • No default exports, always use named exports.
  • Use discriminated unions over optional properties for more complex types.
  • Break statements across multiple lines:
// Wrong.
this.emit('agent:status', { state: 'thinking', message: 'Processing your request…' });

// Right.
this.emit('agent:status', {
  state: 'thinking',
  message: 'Processing your request…'
});
  • When using declarative code, for example, using Zod or Drizzle schemas, write the declarative code by formatting it with each property or method on a new line. For example:
/**
 * Schema for validating user data.
 */
const UserSchema = z.object({
  
  /**
   * The unique identifier for the user.
   * @uuid
   */
  id: z
    .string()
    .uuid()
    .describe('The unique identifier for the user.'),

  /**
   * The name of the user.
   * @min 1 character
   * @max 100 characters
   */
  name: z
    .string()
    .min(1)
    .max(100)
    .describe('The name of the user.'),

  /**
   * The email of the user.
   */
  email: z
    .string()
    .email()
    .describe('The email of the user.')
});

Enums vs. Types

Prefer TypeScript type over enum. Use union for simple value sets and as const objects when you need both runtime values and type inference.

// Simple.
type Status = 'active' | 'inactive';

// Multi-line.
type UserRole =
  | 'admin'
  | 'editor'
  | 'viewer'
  | 'guest';

Function Chaining

When chaining multiple function calls using a fluent interface:

const result = object
  .map(arg1, arg2)
  .reduce(arg3)
  .pipe(arg4);

Object Literals

When defining object literals, format the code with each property on a new line.

const obj = {
  prop1: value1,
  prop2: value2,
  prop3: value3
};

Curly Braces

Always use curly braces for blocks.

For example:

// Wrong.
if (condition) order();

// Wrong.
if (condition)
  order();

// Right.
if (condition) {
  order();
}

Organization

  • Types are always co-located with their implementation and define a single type, or multiple closely related types. Avoid "types-only" files that export unrelated types.
  • Organize code by feature or module under specific directories.
  • Avoid global type augmentation when possible.
  • Store code in a src/ directory, with subdirectories for features or modules.

Comments

  • Use JSDoc comments for functions, types, enums, classes, methods, and class properties. Class properties are always defined at the top of the class, before the constructor. Example:
/**
 * Calculates the area of a rectangle.
 * @param width - The width of the rectangle.
 * @param height - The height of the rectangle.
 * @returns The area of the rectangle.
 */
const calculateArea = (width: number, height: number) => {
  return (width * height);
};
/**
 * Properties for a custom order.
 */
export type CustomOrderProps = {

  /**
   * The unique identifier for the order.
   */
  id: string;

  /**
   * The product being ordered.
   */
  product: string;

  /**
   * The quantity to be ordered.
   */
  quantity: number;
};

/**
 * The `CustomOrder` class represents a custom order in the system.
 */
export class CustomOrder {

  /**
   * Creates a new custom order.
   * @param props - The properties of the custom order.
   * @constructor
   */
  constructor(private props: CustomOrderProps) {}

  /**
   * Computes the total price of the order.
   * @returns The total price of the order.
   */
  getTotalPrice() {
    // Implementation goes here.
  }
}
  • Only use @type in JSDoc comments when the type or unit is non-obvious.
/**
 * The default timeout for API requests.
 * @type {number} in milliseconds
 */
const DEFAULT_TIMEOUT = 5_000;
  • Do not use decorative separators (e.g., -, // --------, // ========) in comments.
  • Use inline comments to explain what the code is doing and why.
/**
 * Issues an API request to the given URL and returns the response data.
 * @param url - The URL to send the request to.
 * @returns The response data from the API.
 */
const request = async (url: URL) => {
  const response = await fetch(url);
    
  // Check for successful response.
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  // Validate response with Zod.
  const result = ResponseSchema.safeParse(
    await response.json()
  );
  if (!result.success) {
    throw new Error(`Invalid response format: ${result.error.message}`);
  }
  
  return (result.data);
};
  • Do not comment the top of files with a description of the file's purpose.
  • Do not use single-line block comments (/** ... */) for function or type declarations. Use multi-line JSDoc comments instead.

Globals

Use multi-line comments for global variables or constants. Globals should be defined at the top of the file, after imports and before any other code.

/**
 * The default timeout for API requests.
 * @type {number} in milliseconds
 */
const DEFAULT_TIMEOUT = 5_000;

Performance

  • Prefer Map and Set over plain objects for frequent lookups.
  • Avoid unnecessary spread copies in hot paths.
  • Use Promise.all() for independent async operations; Promise.allSettled() when dealing with partial failure.

Anti-Patterns

  • No Object or Array constructors — use literals {} and [].
  • No eval() or Function constructor.
  • No with statements.
  • No deep nesting of callbacks or conditionals.
  • Avoid non-null assertions (!).
  • No over-annotation of inferred types when not necessary.
  • Avoid Barrel files as they break tree-shaking, slow down bundlers and IDE indexing, create circular dependency traps, and inflate bundle sizes.
  • No static-only classes.
  • No nested ternaries — max one level deep.
  • No magic numbers / strings — extract to named constants.
  • No prototype manipulation.
  • No unbounded or user-supplied regular expressions — avoid catastrophic backtracking (ReDoS). Prefer simple patterns, use non-backtracking quantifiers, or validate regex complexity before execution.

Logging

See the reference guide for details.

Architecture

See the reference guide for details.

Security

See the reference guide for details.

Testing

  • Use vitest for unit and integration testing.
  • Use supertest for HTTP endpoint testing when a headless browser is not needed.
  • Write tests per feature or component in a dedicated tests/ directory within each associated package. For monorepos, each package should have its own tests/ directory and test configuration.
  • Under the tests/ directory, organize tests by type (e.g., unit/, integration/, e2e/).

Environment

For every project using environment variables, always use an env.ts file that defines and exports all expected environment variables with proper types. Use zod to validate these variables at runtime.

/**
 * Environment variable schema definition.
 */
const envSchema = z.object({

  /**
   * The Supabase region where the function is executing.
   * Automatically set by Supabase runtime.
   * @optional Available only in deployed environments
   */
  SB_REGION: z
    .string()
    .optional(),

  /**
   * Unique identifier for the current function execution.
   * Automatically set by Supabase runtime.
   * @optional Available only in deployed environments
   */
  SB_EXECUTION_ID: z
    .string()
    .optional(),

  /**
   * The current environment (development, staging, production).
   * Used for conditional logic and logging.
   * @default "development"
   */
  ENVIRONMENT: z
    .enum(['development', 'staging', 'production'])
    .default('development')
});

/**
 * Parse and validate environment variables.
 * @throws {z.ZodError} If validation fails, with detailed error messages
 * @returns Validated and typed environment variables
 */
const parseEnv = (): Env => {
  try {
    return envSchema.parse({
      SB_REGION: process.env.SB_REGION,
      SB_EXECUTION_ID: process.env.SB_EXECUTION_ID,
      ENVIRONMENT: process.env.ENVIRONMENT
    });
  } catch (error) {
    // Log the error with details for debugging.
    throw error;
  }
};

/**
 * Validated environment variables.
 *
 * Import this constant to access typed, validated environment variables
 * throughout your Edge Functions.
 */
export const env = parseEnv();

Tooling

Code Quality & Type Safety

ToolPurpose
ZodRuntime validation and type inference for complex data structures.
oxlintCode linter.
oxfmtCode formatter.
tscTypeScript compiler for type checking and transpilation.
tsxTypeScript execution environment for running TS files directly.

Tests

ToolPurpose
vitestFast and lightweight testing framework with built-in TypeScript support.
supertestHTTP assertions for testing API endpoints without a headless browser.

HTTP Stress Testing

ToolPurpose
wrkHigh-performance HTTP benchmarking tool for load testing APIs.
k6Modern load testing tool with scripting in JavaScript/TypeScript.
autocannonFast HTTP/1.1 benchmarking tool for stress testing APIs.

Web Page Testing

ToolPurpose
playwrightEnd-to-end testing framework for web applications with TypeScript support.
puppeteerHeadless Chrome Node API for web page testing and automation.

Database & ORMs

NeedUseWhy
ORMDrizzleSQL-like API, fully type-safe, zero overhead, supports Postgres/MySQL/SQLite
Query builderKyselyType-safe raw SQL builder, no magic, great for complex queries

Zod-specific Guidelines

  • Define schemas in dedicated files.
  • Use z.infer<typeof Schema> to derive types from Zod schemas.
  • Use .describe() to add descriptions to schema properties.

Package Managers

Package ManagerUse Case
pnpmDefault for Node.js projects.
bunUse when the project is Bun-based.
npmUse when the project is Node.js-based and there's a specific reason to choose npm.

Files

Add the following files to your project.

FilePurpose
.oxfmtrc.jsonOxlint configuration in references/config/
.oxlintrc.jsonOxfmt configuration in references/config/
tsconfig.jsonTypeScript configuration in references/config/.
.gitignoreSpecifies files and directories to ignore in version control.
nx.json or turbo.jsonConfiguration for monorepo management with Nx or Turborepo.
.nvmrcSpecifies the Node.js version for the project.

CI/CD

ToolPurpose
GitHub ActionsCI/CD pipelines for automated testing, linting, and deployment.
tsc --noEmitType-check step — run in CI to catch type errors before merge.
vitest runRun tests.

Reference Files

The references/config directory contains starter configurations:

  • .oxlintrc.json — Oxlint configuration with rules for TypeScript projects.
  • .oxfmtrc.json — Oxfmt configuration for consistent code formatting.
  • tsconfig.json — TypeScript compiler options with strict: true.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.