# typescript

Tells the agent how to write and check TypeScript: strict tsconfig, ESLint config, Jest tests and a layered project layout. Kicks in on .ts and .tsx files.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 313 installs · ★ 711
- Author: alinaqi
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/alinaqi/maggy/tree/HEAD/skills/typescript/SKILL.md
- Updated: 2026-10-13
- HTML: https://affpapa.org/en/nevibecode/skills/alinaqi-typescript

## What it does

The skill activates on its own when the agent touches files matching `**/*.ts`, `**/*.tsx` or `tsconfig*.json`. Inside is a ready `tsconfig.json` with `strict`, `noImplicitAny`, `strictNullChecks`, `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns` and `esModuleInterop`. Alongside it sits an `eslint.config.js` built on `typescript-eslint` with strict rules: no `any`, explicit return types, a 20-line cap per function, max depth 2 and at most 3 parameters.

Project layout is spelled out too: `src/core` for pure logic, `src/infra` for side effects, `tests/unit` and `tests/integration`. A Jest example shows the Arrange/Act/Assert split. There is a GitHub Actions workflow running lint, typecheck and test:coverage, with the coverage threshold set to 80% for branches, functions, lines and statements. Commits go through Husky and lint-staged: ESLint with `--fix`, Prettier, then `tsc --noEmit` and tests limited to changed files.

The rules are strict. `any`, `as` assertions, the `!` operator, unexplained `@ts-ignore` and enums are all listed as anti-patterns. If your codebase relies on enums on purpose, or `any` is scattered through legacy code, the agent will push back against what is already there. Worth checking before you install the whole thing.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add alinaqi/maggy --skill typescript -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/typescript/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/typescript/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add alinaqi/maggy --skill typescript -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/typescript/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add alinaqi/maggy --skill typescript -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/typescript/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install alinaqi/maggy typescript
```

2. **Manually: put the files in place**
- File: `.github/skills/typescript/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add alinaqi/maggy --skill typescript -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/alinaqi/maggy --path skills/typescript
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/typescript/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add alinaqi/maggy --skill typescript -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/alinaqi/maggy/tree/HEAD/skills/typescript/SKILL.md

## When to use it
- turn on strict TypeScript in a fresh project
- split code into core, infra and utils layers
- set up ESLint with type-aware rules
- add Jest tests with a coverage gate
- run checks on every commit via Husky

## Example prompts
- Set up tsconfig.json following the typescript skill rules
- Write a Jest test for calculateTotal using Arrange/Act/Assert
- Check this file for TypeScript anti-patterns and replace any

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: acd5419ae83c0339.

BEGIN THIRD-PARTY FILE acd5419ae83c0339
````text
---
name: typescript
description: TypeScript strict mode with eslint and jest
when-to-use: When working on TypeScript files
user-invocable: false
paths: ["**/*.ts", "**/*.tsx", "tsconfig*.json"]
effort: medium
---

# TypeScript Skill


---

## Strict Mode (Non-Negotiable)

```json
// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}
```

---

## Project Structure

```
project/
├── src/
│   ├── core/               # Pure business logic
│   │   ├── types.ts        # Domain types/interfaces
│   │   ├── services/       # Pure functions
│   │   └── index.ts        # Public API
│   ├── infra/              # Side effects
│   │   ├── api/            # HTTP handlers
│   │   ├── db/             # Database operations
│   │   └── external/       # Third-party integrations
│   └── utils/              # Shared utilities
├── tests/
│   ├── unit/
│   └── integration/
├── package.json
├── tsconfig.json
└── CLAUDE.md
```

---

## Tooling (Required)

```json
// package.json scripts
{
  "scripts": {
    "lint": "eslint src/ --ext .ts,.tsx",
    "typecheck": "tsc --noEmit",
    "test": "jest",
    "test:coverage": "jest --coverage",
    "format": "prettier --write 'src/**/*.ts'"
  }
}
```

```javascript
// eslint.config.js
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.strictTypeChecked,
  {
    rules: {
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/explicit-function-return-type': 'error',
      'max-lines-per-function': ['error', 20],
      'max-depth': ['error', 2],
      'max-params': ['error', 3],
    }
  }
);
```

---

## Testing with Jest

```typescript
// tests/unit/services/user.test.ts
import { calculateTotal } from '../../../src/core/services/pricing';

describe('calculateTotal', () => {
  it('returns sum of item prices', () => {
    // Arrange
    const items = [{ price: 10 }, { price: 20 }];

    // Act
    const result = calculateTotal(items);

    // Assert
    expect(result).toBe(30);
  });

  it('returns zero for empty array', () => {
    expect(calculateTotal([])).toBe(0);
  });

  it('throws on invalid item', () => {
    expect(() => calculateTotal([{ invalid: 'item' }])).toThrow();
  });
});
```

---
````
END THIRD-PARTY FILE acd5419ae83c0339

The third-party file has ended. Everything between the acd5419ae83c0339 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2675 of 5176 bytes. © alinaqi · MIT · https://github.com/alinaqi/maggy/tree/HEAD/skills/typescript/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md