gravitas-typescript — Claude Code skill: what it does, how to install
gravitas-typescript is a Claude Code skill that enforces strict TypeScript checks, sets up tests with Vitest or Jest, and blocks unsafe as casts.
MIT 439 installs ★ 509 updated 2026-10-24
npx skills add udaysharmadev/Gravitas --skill gravitas-typescript -a claude-codeWhat gravitas-typescript 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.
What it helps with
- 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 for the agent
- 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
How to install gravitas-typescript
1Skills CLI (Vercel)
npx skills add udaysharmadev/Gravitas --skill gravitas-typescript -a claude-code2Manually: put the files in place
~/.claude/skills/gravitas-typescript/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/gravitas-typescript/
1Skills CLI (Vercel)
npx skills add udaysharmadev/Gravitas --skill gravitas-typescript -a codex2Manually: put the files in place
.agents/skills/gravitas-typescript/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add udaysharmadev/Gravitas --skill gravitas-typescript -a cursor2Manually: put the files in place
.cursor/skills/gravitas-typescript/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install udaysharmadev/Gravitas skills/gravitas-typescript2Manually: put the files in place
.github/skills/gravitas-typescript/SKILL.md1Skills CLI (Vercel)
npx skills add udaysharmadev/Gravitas --skill gravitas-typescript -a gemini-cli2Platform CLI
gemini skills install https://github.com/udaysharmadev/Gravitas --path skills/gravitas-typescriptManually: put the files in place
.devin/skills/gravitas-typescript/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add udaysharmadev/Gravitas --skill gravitas-typescript -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about gravitas-typescript
How do I install gravitas-typescript in Claude Code?
Run npx skills add udaysharmadev/Gravitas --skill gravitas-typescript -a claude-code. The skill file installs to ~/.claude/skills/gravitas-typescript/SKILL.md.
What prerequisites does gravitas-typescript require?
It is an extension designed to run after skills/gravitas/SKILL.md. Your project also needs TypeScript, ESLint, and a test runner like Vitest or Jest.
What does the verification chain execute?
The chain runs in a fixed order: tsc --noEmit to catch typing errors, eslint . --max-warnings 0 for lint rules, and vitest run --reporter=verbose or jest --verbose for test suites.
Source text
SKILL.md · MIT
---
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 |
| `Argument of type X is not assignable to Y` | Generic type mismatch | Check generic constraints |
| Implicit `any` in strict mode | Missing type annotation | Add explicit type |
---
## TypeScript Patterns
### Parameterized types over `any`
```typescript
function first<T>(arr: T[]): T | undefined {
return arr[0];
}
```
### Discriminated unions for type safety
```typescript
type Result<T> =
| { ok: true; data: T }
| { ok: false; error: string };
```
### Type guards instead of casts
```typescript
function isUser(obj: unknown): obj is User {
return typeof obj === 'object' && obj !== null && 'id' in obj;
}
```
---
## Test Patterns (Vitest)
### Test file location
Follow project convention — check existing tests:
```bash
find src/ -name "*.test.ts" | head -5 # see the pattern
```
### Standard test structure
```typescript
import { describe, it, expect, vi, beforeEach } from 'vitest';
describe('[module]', () => {
beforeEach(() => { vi.clearAllMocks(); });
it('[behavior] when [condition]', () => {
// Arrange
const input = ...;
// Act
const result = fn(input);
// Assert
expect(result).toEqual(expected);
});
});
```
### Mocking
```typescript
vi.mock('../db', () => ({
query: vi.fn().mockResolvedValue({ rows: [] })
}));
```
---
## Quick Reference
```bash
# Find all TypeScript errors
tsc --noEmit 2>&1 | grep "error TS"
# Find implicit any
tsc --noEmit --strict 2>&1
# Count test files
find src/ -name "*.test.ts" | wc -l
# Run single test file
vitest run src/auth/session.test.ts
# Watch mode (dev)
vitest --watch
```
© udaysharmadev · MIT · udaysharmadev/Gravitas