typescript

Name: typescript
Author: sordi-ai

17stars3forks

How to install typescript?

sordi-ai/skill-everything/typescript

$npx -y skills add sordi-ai/skill-everything --skill typescript

Installs into the current project.

Summary

Apply when writing TypeScript code. Strict types, discriminated unions, async patterns, and runtime safety.

Files · 1

View on GitHub

SKILL.md

1	# Sub-Skill: TypeScript Best Practices
2	<!-- target: ~2500 tokens (real tiktoken count) \| 17 rules with severity classification -->
3
4	Purpose: Prevents the TypeScript-specific mistakes LLMs make repeatedly — weak types, unsafe assertions, and patterns that compile but fail at runtime.
5
6	## Rule classification
7
8	- MUST — load-bearing. Violating leaks runtime errors past the type checker. Never break.
9	- SHOULD — default behavior. Deviation needs a documented reason in the code or PR.
10	- AVOID — usually wrong; documented exception inline where needed.
11
12	Where these rules don't strictly apply: test fixtures, generated types (e.g. from GraphQL codegen, OpenAPI generators, Prisma), declaration files (`.d.ts`) for untyped third-party libraries, and migration scripts may legitimately differ. The rules below apply to production application code*.
13
14	---
15
16	## Type Safety
17
18	1. MUST: Never use `any`. Use `unknown` and narrow it. `any` disables the type checker entirely. `unknown` forces you to prove the type before use. Exception: third-party libraries without types and explicit dynamic-data boundaries (e.g. JSON parse at the API edge), with a comment explaining why.
19	```ts
20	// Wrong
21	function parse(data: any) { return data.name; }
22
23	// Correct
24	function parse(data: unknown): string {
25	if (typeof data === 'object' && data !== null && 'name' in data) {
26	return String((data as { name: unknown }).name);
27	}
28	throw new Error('Invalid data shape');
29	}
30	```
31
32	2. AVOID: `Object` or `{}` as a type. Both accept nearly everything. Use `Record<string, unknown>` for arbitrary objects or define an explicit interface.
33	```ts
34	// Wrong
35	function merge(a: {}, b: Object): {} { ... }
36
37	// Correct
38	function merge<T extends Record<string, unknown>>(a: T, b: Partial<T>): T { ... }
39	```
40
41	3. SHOULD: Use `as` only when you know more than the compiler — and document why. Prefer type guards or `satisfies` instead.
42	```ts
43	// Wrong — silences the error, hides the bug
44	const user = response.data as User;
45
46	// Correct — validate first
47	function isUser(v: unknown): v is User {
48	return typeof v === 'object' && v !== null && 'id' in v && 'email' in v;
49	}
50	const user = isUser(response.data) ? response.data : null;
51	```
52
53	4. SHOULD: Mark immutable data `readonly`. Prevents accidental mutation and communicates intent.
54	```ts
55	// Avoid
56	function process(ids: string[]) { ids.push('extra'); }
57
58	// Prefer
59	function process(ids: readonly string[]) { /* ids.push() is a compile error */ }
60	```
61
62	5. MUST: Enable `strictNullChecks` and handle every `T \| undefined`. Optional chaining `?.` returns `undefined` — always handle that branch.
63	```ts
64	// Wrong
65	const name = user?.profile.name.toUpperCase(); // crashes if name is undefined
66
67	// Correct
68	const name = user?.profile.name?.toUpperCase() ?? 'Anonymous';
69	```
70
71	6. SHOULD: Use branded types for IDs. Prevents passing a `UserId` where an `OrderId` is expected — both are `string` at runtime.
72	```ts
73	type UserId = string & { readonly _brand: 'UserId' };
74	type OrderId = string & { readonly _brand: 'OrderId' };
75
76	function createUserId(raw: string): UserId { return raw as UserId; }
77
78	function getUser(id: UserId): User { ... }
79	// getUser(orderId) → compile error
80	```
81
82	---
83
84	## Patterns
85
86	7. SHOULD: Use discriminated unions for state, not optional fields. Optional fields force you to reason about all combinations. A discriminated union makes illegal states unrepresentable.
87	```ts
88	// Avoid — 8 possible combinations, most invalid
89	type Request = { loading?: boolean; data?: User; error?: Error };
90
91	// Prefer — exactly 3 valid states
92	type Request =
93	\| { status: 'idle' }
94	\| { status: 'loading' }
95	\| { status: 'success'; data: User }
96	\| { status: 'error'; error: Error };
97	```
98
99	8. SHOULD: Use `satisfies` to validate shape without widening the type. `as const` preserves literals; `satisfies` validates against an interface without losing them.
100	```ts
101	const config = {
102	host: 'localhost',
103	port: 5432,
104	} satisfies DatabaseConfig;
105	// config.port is still typed as 5432, not number
106	```
107
108	9. SHOULD: Use `const` objects instead of `enum`. Enums emit runtime code, have surprising reverse-mapping behavior, and are not idiomatic TypeScript.
109	```ts
110	// Avoid
111	enum Direction { Up, Down, Left, Right }
112
113	// Prefer
114	const Direction = { Up: 'Up', Down: 'Down', Left: 'Left', Right: 'Right' } as const;
115	type Direction = typeof Direction[keyof typeof Direction];
116	```
117
118	10. AVOID: Barrel `index.ts` re-exports in large modules. They caus

People who liked this also viewed

6 picks

Type

caveman-commitUltra-compressed commit message generator. Cuts noise from commit messages while preserving intent and reasoning. Conventional Commits format. Subject ≤50 chars, body only when "why" isn't obvious. UsSkillsJul 2026259k92k
git-guardrails-claude-codeSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026157k181k
setup-pre-commitSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026152k181k
resolving-merge-conflictsSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026146k181k
using-git-worktreesUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackSkillsJul 2026143k259k
finishing-a-development-branchUse when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanupSkillsJul 2026140k259k

typescript

17stars3forks

View on GitHub

How to install typescript?

sordi-ai/skill-everything/typescript

$npx -y skills add sordi-ai/skill-everything --skill typescript

Installs into the current project.

Summary

Apply when writing TypeScript code. Strict types, discriminated unions, async patterns, and runtime safety.

Files · 1

View on GitHub

SKILL.md

1	# Sub-Skill: TypeScript Best Practices
2	<!-- target: ~2500 tokens (real tiktoken count) \| 17 rules with severity classification -->
3
4	Purpose: Prevents the TypeScript-specific mistakes LLMs make repeatedly — weak types, unsafe assertions, and patterns that compile but fail at runtime.
5
6	## Rule classification
7
8	- MUST — load-bearing. Violating leaks runtime errors past the type checker. Never break.
9	- SHOULD — default behavior. Deviation needs a documented reason in the code or PR.
10	- AVOID — usually wrong; documented exception inline where needed.
11
12	Where these rules don't strictly apply: test fixtures, generated types (e.g. from GraphQL codegen, OpenAPI generators, Prisma), declaration files (`.d.ts`) for untyped third-party libraries, and migration scripts may legitimately differ. The rules below apply to production application code*.
13
14	---
15
16	## Type Safety
17
18	1. MUST: Never use `any`. Use `unknown` and narrow it. `any` disables the type checker entirely. `unknown` forces you to prove the type before use. Exception: third-party libraries without types and explicit dynamic-data boundaries (e.g. JSON parse at the API edge), with a comment explaining why.
19	```ts
20	// Wrong
21	function parse(data: any) { return data.name; }
22
23	// Correct
24	function parse(data: unknown): string {
25	if (typeof data === 'object' && data !== null && 'name' in data) {
26	return String((data as { name: unknown }).name);
27	}
28	throw new Error('Invalid data shape');
29	}
30	```
31
32	2. AVOID: `Object` or `{}` as a type. Both accept nearly everything. Use `Record<string, unknown>` for arbitrary objects or define an explicit interface.
33	```ts
34	// Wrong
35	function merge(a: {}, b: Object): {} { ... }
36
37	// Correct
38	function merge<T extends Record<string, unknown>>(a: T, b: Partial<T>): T { ... }
39	```
40
41	3. SHOULD: Use `as` only when you know more than the compiler — and document why. Prefer type guards or `satisfies` instead.
42	```ts
43	// Wrong — silences the error, hides the bug
44	const user = response.data as User;
45
46	// Correct — validate first
47	function isUser(v: unknown): v is User {
48	return typeof v === 'object' && v !== null && 'id' in v && 'email' in v;
49	}
50	const user = isUser(response.data) ? response.data : null;
51	```
52
53	4. SHOULD: Mark immutable data `readonly`. Prevents accidental mutation and communicates intent.
54	```ts
55	// Avoid
56	function process(ids: string[]) { ids.push('extra'); }
57
58	// Prefer
59	function process(ids: readonly string[]) { /* ids.push() is a compile error */ }
60	```
61
62	5. MUST: Enable `strictNullChecks` and handle every `T \| undefined`. Optional chaining `?.` returns `undefined` — always handle that branch.
63	```ts
64	// Wrong
65	const name = user?.profile.name.toUpperCase(); // crashes if name is undefined
66
67	// Correct
68	const name = user?.profile.name?.toUpperCase() ?? 'Anonymous';
69	```
70
71	6. SHOULD: Use branded types for IDs. Prevents passing a `UserId` where an `OrderId` is expected — both are `string` at runtime.
72	```ts
73	type UserId = string & { readonly _brand: 'UserId' };
74	type OrderId = string & { readonly _brand: 'OrderId' };
75
76	function createUserId(raw: string): UserId { return raw as UserId; }
77
78	function getUser(id: UserId): User { ... }
79	// getUser(orderId) → compile error
80	```
81
82	---
83
84	## Patterns
85
86	7. SHOULD: Use discriminated unions for state, not optional fields. Optional fields force you to reason about all combinations. A discriminated union makes illegal states unrepresentable.
87	```ts
88	// Avoid — 8 possible combinations, most invalid
89	type Request = { loading?: boolean; data?: User; error?: Error };
90
91	// Prefer — exactly 3 valid states
92	type Request =
93	\| { status: 'idle' }
94	\| { status: 'loading' }
95	\| { status: 'success'; data: User }
96	\| { status: 'error'; error: Error };
97	```
98
99	8. SHOULD: Use `satisfies` to validate shape without widening the type. `as const` preserves literals; `satisfies` validates against an interface without losing them.
100	```ts
101	const config = {
102	host: 'localhost',
103	port: 5432,
104	} satisfies DatabaseConfig;
105	// config.port is still typed as 5432, not number
106	```
107
108	9. SHOULD: Use `const` objects instead of `enum`. Enums emit runtime code, have surprising reverse-mapping behavior, and are not idiomatic TypeScript.
109	```ts
110	// Avoid
111	enum Direction { Up, Down, Left, Right }
112
113	// Prefer
114	const Direction = { Up: 'Up', Down: 'Down', Left: 'Left', Right: 'Right' } as const;
115	type Direction = typeof Direction[keyof typeof Direction];
116	```
117
118	10. AVOID: Barrel `index.ts` re-exports in large modules. They caus

People who liked this also viewed

6 picks

Type