typescript-best-practices — Claude Code skill: TypeScript rules
A skill that hands the agent a rulebook for .ts and .tsx files: discriminated unions, branded types, validation at the boundary.
npx skills add cursor/plugins --skill typescript-best-practices -a claude-codeWhat typescript-best-practices does
The skill fires whenever the agent opens or edits a .ts or .tsx file. Its table of rules covers modeling variants with a literal kind discriminant, branding primitives via & { readonly __brand: "X" }, and keeping outside data in unknown rather than any.
A second group deals with narrowing. The order runs from a discriminant switch down to as, user-defined type guards have to actually verify what they claim, and default arms carry const _exhaustive: never = x; so a new variant breaks the build. Schemas come before hand-written guards, with the type inferred from the schema, z.infer being the example given. Every as is treated as a runtime crash waiting to happen — cast only after validation.
Two principle skills are named as prerequisites: **type-system-discipline** and **boundary-discipline**, applied first. Pattern examples live in references/patterns.md. Install runs through npx skills add with a per-platform flag; GitHub Copilot takes a different command, gh skill install.
What it helps with
- model state variants so impossible combinations fail to compile
- swap scattered
ascasts for boundary validation and named domain types - infer a type from a runtime schema instead of hand-writing a property guard
- add an exhaustiveness check that catches a new variant at build time
- move shipped code off
console.logonto a structured logger
Example prompts for the agent
- Review this
.tsfile against the skill rules and drop everyas - Rewrite this optional-field bag as a discriminated union on
kind - Add an exhaustiveness check to the
switchover API response variants
How to install typescript-best-practices
1Skills CLI (Vercel)
npx skills add cursor/plugins --skill typescript-best-practices -a claude-code2Manually: put the files in place
~/.claude/skills/typescript-best-practices/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/typescript-best-practices/
1Skills CLI (Vercel)
npx skills add cursor/plugins --skill typescript-best-practices -a codex2Manually: put the files in place
.agents/skills/typescript-best-practices/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add cursor/plugins --skill typescript-best-practices -a cursor2Manually: put the files in place
.cursor/skills/typescript-best-practices/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install cursor/plugins typescript-best-practices2Manually: put the files in place
.github/skills/typescript-best-practices/SKILL.md1Skills CLI (Vercel)
npx skills add cursor/plugins --skill typescript-best-practices -a gemini-cli2Platform CLI
gemini skills install https://github.com/cursor/plugins --path pstack/skills/typescript-best-practicesManually: put the files in place
.devin/skills/typescript-best-practices/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add cursor/plugins --skill typescript-best-practices -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 typescript-best-practices
How do I install typescript-best-practices in Claude Code?
Run npx skills add cursor/plugins --skill typescript-best-practices -a claude-code. The skill lands at ~/.claude/skills/typescript-best-practices/SKILL.md.
What does typescript-best-practices do?
It gives the agent a set of TypeScript rules: discriminated unions, branded types, unknown over any, boundary validation, exhaustiveness checks. It activates when a .ts or .tsx file is read or edited.
Which other platforms can install this skill?
Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode each have their own flag or command. GitHub Copilot uses gh skill install cursor/plugins typescript-best-practices.
