# luau-type-expert

luau-type-expert works through Luau type errors and gets a file to --!strict: generics, unions, narrowing with type(), and :: casts.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 308 installs · ★ 5 repo stars
- Author: dig1t
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/dig1t/skills/tree/HEAD/luau-type-expert/SKILL.md
- Updated: 2026-10-01
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/luau-type-expert

## What it does

Reach for this skill when `luau-lsp` or `luau-analyze` reports a type problem and you want the annotation fixed rather than silenced. It covers the three file modes (`--!nocheck`, `--!nonstrict`, `--!strict`), annotation syntax, generic functions and aliases with constraints, discriminated unions, and narrowing that follows `type()`, `typeof()` and truthiness checks. Early returns keep their narrowing, which is what guard clauses need.

Four reference files come with it: `api_reference.md`, `common-errors.md`, `performance.md` and `lint-rules.md`. The error table maps messages like the X-to-Y conversion complaint to a concrete fix, and the lint file goes through all 28 rules.

Typed metatables get their own walkthrough: declaring `__index`, the constructor and methods so `setmetatable` doesn't collapse the object to `any`. For `.luaurc` the skill explains `languageMode`, path aliases such as `@shared` and per-rule lint switches.

A cast only passes when one side is a subtype of the other or `any` — otherwise the error stays put. CLI analysis runs through `luau-lsp analyze`, and a Roblox codebase needs `--sourcemap=sourcemap.json`, or the instance tree won't line up.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add dig1t/skills --skill luau-type-expert -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add dig1t/skills --skill luau-type-expert -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add dig1t/skills --skill luau-type-expert -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install dig1t/skills luau-type-expert
```

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

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add dig1t/skills --skill luau-type-expert -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/dig1t/skills --path luau-type-expert
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add dig1t/skills --skill luau-type-expert -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/dig1t/skills/tree/HEAD/luau-type-expert/SKILL.md

## When to use it
- Clear a "Type X could not be converted into Y" error in a module
- Move an existing file to `--!strict` without a pile of new errors
- Type a metatable-based class with its constructor and `__index`
- Set up `.luaurc` aliases and lint rules
- Load `.d.luau` globals for `luau-lsp analyze`

## Example prompts
- Why does `luau-lsp` flag a type error in `Inventory.luau`, and how do I fix it?
- Convert `PlayerData.luau` to `--!strict` and explain each change
- Write the type for a `Vector2` class with a metatable so `setmetatable` keeps the type

## Similar
- [roblox-luau-types](https://affpapa.org/en/nevibecode/skills/roblox-luau-types.md) — skill · 3400 installs
- [roblox-luau-patterns](https://affpapa.org/en/nevibecode/skills/roblox-luau-patterns.md) — skill · 3500 installs
- [roblox-physics](https://affpapa.org/en/nevibecode/skills/el4cteo-roblox-physics.md) — skill · 1200 installs
- [scenario-roblox-luau](https://affpapa.org/en/nevibecode/skills/scenario-roblox-luau.md) — skill · 351 installs
- [roblox-ui](https://affpapa.org/en/nevibecode/skills/roblox-ui.md) — skill · 9900 installs
- [roblox-analytics-liveops](https://affpapa.org/en/nevibecode/skills/roblox-analytics-liveops.md) — skill · 1200 installs

From the same set: [dig1t/skills](https://affpapa.org/en/nevibecode/by/dig1t/skills.md) — 3 cards

---
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
