# gravitas-typescript

gravitas-typescript is a Claude Code skill that enforces strict TypeScript checks, sets up tests with Vitest or Jest, and blocks unsafe as casts.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 439 installs · ★ 509 repo stars
- Author: udaysharmadev
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/udaysharmadev/Gravitas/tree/HEAD/skills/gravitas-typescript/SKILL.md
- Updated: 2026-10-24
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/gravitas-typescript

## What it does

This skill adds TypeScript guidelines on top of the base GRAVITAS workflow. During recon, it inspects `tsconfig.json` using `jq` to verify flags like `strict`, `noUncheckedIndexedAccess`, and `exactOptionalPropertyTypes`. It also checks package versions and maps path aliases before touching any application code.

Verification follows a strict sequence: `tsc --noEmit` runs first, followed by `eslint . --max-warnings 0`, and finishes with `vitest` or `jest`. The skill blocks common anti-patterns like `any` and silencing compiler errors via `as`. Instead, it directs the agent toward discriminated unions, explicit undefined checks, and runtime type guards.

You must load `skills/gravitas/SKILL.md` before using this extension. Without the base GRAVITAS skill present, the agent lacks the core operational context.

## Install

### Claude Code (native platform)

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

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add udaysharmadev/Gravitas --skill gravitas-typescript -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add udaysharmadev/Gravitas --skill gravitas-typescript -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install udaysharmadev/Gravitas skills/gravitas-typescript
```

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

### Gemini CLI

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

2. **Platform CLI**
```bash
gemini skills install https://github.com/udaysharmadev/Gravitas --path skills/gravitas-typescript
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add udaysharmadev/Gravitas --skill gravitas-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/udaysharmadev/Gravitas/tree/HEAD/skills/gravitas-typescript/SKILL.md

## When to use it
- Audit compiler flags in tsconfig.json for strict null and property checks
- Eliminate unsafe as type assertions and explicit or implicit any
- Run the verification sequence across tsc, eslint, and vitest
- Implement discriminated unions and runtime guards for unknown payloads

## Example prompts
- Audit tsconfig.json and report missing strict compiler options
- Run the TypeScript verification chain on the auth module
- Refactor type assertions in this file into safe type guards

## 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: 502bcd769580ae50.

BEGIN THIRD-PARTY FILE 502bcd769580ae50
````text
---
name: gravitas-typescript
description: >
  GRAVITAS extension for TypeScript projects. Adds TypeScript-specific recon,
  strict mode patterns, Vitest/Jest integration, and common TS failure modes.
  Load in addition to the base GRAVITAS skill.
triggers:
  - "typescript"
  - "ts"
  - "tsx"
  - "react"
  - "next"
  - "vitest"
  - "jest"
---

# GRAVITAS — TypeScript Extension

Extends the base GRAVITAS skill with TypeScript-specific patterns.
Load `skills/gravitas/SKILL.md` first, then this file.

---

## TypeScript Recon Additions

Add to standard recon checklist:

```
□ tsconfig.json — strict mode? noUncheckedIndexedAccess? exactOptionalPropertyTypes?
□ package.json — TypeScript version, test runner (vitest vs jest)
□ eslint config — @typescript-eslint rules in effect
□ type declarations — are there .d.ts files that affect this module?
□ path aliases — does tsconfig have paths? (affects imports)
```

### Read tsconfig strictly

```bash
cat tsconfig.json | jq '.compilerOptions | {strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, target, lib}'
```

---

## TypeScript Verification Chain

```bash
# Full chain — always in this order
tsc --noEmit                           # catches type errors first
eslint . --max-warnings 0              # @typescript-eslint rules
vitest run --reporter=verbose          # or: jest --verbose

# With coverage
vitest run --coverage --reporter=verbose

# Type coverage (optional, requires type-coverage)
npx type-coverage --strict
```

---

## TypeScript-Specific Anti-Patterns

### Never use `any`
```typescript
BAD:  function process(data: any) { ... }
GOOD: function process(data: ProcessInput) { ... }
```

### Never use `as` to silence type errors
```typescript
BAD:  const user = data as User;  // silences real type error
GOOD: if (isUser(data)) { const user = data; ... }
```

### Handle `undefined` explicitly
```typescript
BAD:  const name = user.name;          // may be undefined
GOOD: const name = user.name ?? 'Anonymous';
```

### Strict null checks
```typescript
BAD:  return users.find(u => u.id === id).name;  // crash if not found
GOOD: return users.find(u => u.id === id)?.name;
```

---

## Common TypeScript Failure Modes

| Failure | Root Cause | Fix |
|---------|-----------|-----|
| `Object is possibly undefined` | Optional property accessed without guard | Add `?.` or null check |
| `Type 'string' is not assignable to 'number'` | Wrong type passed | Check function signature, fix caller |
| `Property does not exist on type` | Interface mismatch | Update interface or use correct property |
| `Cannot find module` | Path alias not in tsconfig | Add to `paths` in tsconfig |
````
END THIRD-PARTY FILE 502bcd769580ae50

The third-party file has ended. Everything between the 502bcd769580ae50 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 2686 of 4276 bytes. © udaysharmadev · MIT · https://github.com/udaysharmadev/Gravitas/tree/HEAD/skills/gravitas-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
