Guide writing or changing TypeScript, or JavaScript checked with JSDoc, so its types make real guarantees: learn the project's TypeScript version, tsconfig, runtime and module system first, then validate untrusted data at the boundary instead of casting it, model states with discriminated unions, keep generics that relate something, configure tsconfig and package exports for what actually loads the code, keep declarations in step with runtime behavior, and verify with the project's own type check. Also assesses, on request, whether and how a JavaScript project should adopt TypeScript. Use whenever you create or edit .ts, .tsx, .mts or .cts files, type declarations, a tsconfig, or JSDoc types, even when the user doesn't say TypeScript. It adds no library, upgrade or migration unasked. Not for reviewing code already written (the knackpack:typescript-code-reviewer agent, started only on request), React's own semantics, custom element behavior, or choosing between technologies in general (the research skill).
89%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Write TypeScript the way the project already writes it, so that its types say what the code actually does, and so that nothing breaks at run time that the compiler appeared to accept. Types are erased: every rule here is about the gap between what the compiler checks and what runs. These rules hold for every edit, including a one-line cast.
as, !, a generic argument, an annotation and a .d.ts make claims the compiler believes without proof. Make a claim only when something in reach establishes it, and validate data from outside before typing it.npx (with no terminal attached it downloads and runs missing packages without asking), and never run a fixing or formatting mode over files you didn't change. Use the tools already in node_modules, by path.Read before writing:
typescript version the lockfile resolves. From 7.0 it is the native compiler (still tsc), which has no stable compiler API; 6.0 changed defaults (strict on, module: esnext, target: es2025, types: [], rootDir the tsconfig's folder) and 7.0 removed baseUrl, moduleResolution: node10/classic, target: es5, outFile and AMD/UMD/System. Write code and config for the version installed.extends and references, and note strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, module, moduleResolution, target, lib, isolatedModules, verbatimModuleSyntax, erasableSyntaxOnly, allowJs and checkJs.tsc output run by Node, a bundler that strips types (Vite, esbuild, SWC, Babel), Node's own type stripping, tsx, Bun or Deno. Only tsc checks types.exports, types, type, files, peerDependencies and whether declarations are generated or hand-written.Data from outside has whatever shape the sender chose: JSON.parse, fetch responses, request bodies and parameters, form data, process.env, files, storage, messages, untyped JavaScript modules.
unknown from the source and narrow it; never as it to the domain type.ProcessEnv augmentation.Number("") is 0, Boolean("false") is true.Object.assign or a deep merge into existing objects: a __proto__ key pollutes the prototype. Use spread, structuredClone, Map, or objects created with Object.create(null).!.switch over a closed union, end with default: { const unreachable: never = value; … } so adding a member breaks the build until it's handled. For open sets (values a server may add later), keep that check and add a runtime fallback that logs, rather than throwing in production.erasableSyntaxOnly, or a per-file transpiler (never export a const enum from a library: consumers see it as ambient, which isolatedModules rejects); otherwise follow the project.p?: T (may be absent) and p: T | undefined (present, possibly undefined). Without exactOptionalPropertyTypes the compiler mixes them, so when absence means something to the consumer, build the object without the key rather than with undefined.onPick: (item: Item) => void), not method shorthand, so the compiler checks handler parameters contravariantly.load<T>(): T): it's a cast every caller makes unchecked. Constrain to what the body needs: for a key whose value becomes a string or property key, take a function returning the key ((item: T) => K with K extends PropertyKey) rather than keyof T.async function where a void callback is expected and its completion or errors matter (forEach(async …)).unknown and narrow (err instanceof Error) before reading properties.satisfies to check an object against a type while keeping its literal types, and as const for literal lookup tables.Change configuration only as the task needs, and only for what actually runs the code:
tsc output run by Node needs module: nodenext (or node20) and relative imports with .js extensions; moduleResolution: bundler is for code a bundler loads. Node running .ts directly needs .ts extensions (with rewriteRelativeImportExtensions, or allowImportingTsExtensions and noEmit), erasableSyntaxOnly and verbatimModuleSyntax, and no decorators.isolatedModules (or verbatimModuleSyntax), and import types with import type.lib doesn't polyfill: don't use an API newer than the oldest runtime the project supports just because lib includes it.strict plus noUncheckedIndexedAccess and consider exactOptionalPropertyTypes; in existing ones, raise flags only on request, one at a time, fixing what each reveals.skipLibCheck skips every .d.ts, the project's own included. Don't add it to make an error go away; fix the error, or keep hand-written declarations checked another way.exports exists it's the whole public surface, so list every subpath consumers import; put types first in each condition; give ESM and CommonJS entry points their own declarations. Importing named exports from a CommonJS package into ESM works only if Node can detect them statically; when unsure, import the default and destructure.tsc --declaration where possible; when they're hand-written, update them in the same change as the code, and treat a changed signature as breaking.isolatedDeclarations enforces this where the project uses it.dependencies or peerDependencies.declare global) in a module file, and remember that declare module "pkg" in a file without imports or exports replaces the package's types rather than extending them.In JavaScript files, follow the project: if it checks JS (checkJs, // @ts-check), write accurate JSDoc (@param, @returns, @typedef, @type) whose types say exactly what the code returns, including null and failure cases. TypeScript 7 dropped @enum, constructor-function patterns and Closure-style types in JSDoc. Don't convert files to TypeScript unless asked.
When asked whether a JavaScript project should adopt TypeScript, assess before recommending. Read the code and history rather than guessing:
End with one recommendation and its reasons: full migration, incremental migration, type-checking JavaScript with JSDoc, keeping JavaScript with targeted declarations for the riskiest boundaries, or keeping the current approach. TypeScript is not always the answer. For an incremental plan, give stages: establish checking without changing runtime behavior (often allowJs and checkJs per file), type the shared domain models and boundaries first, convert the modules with the most risk and change, raise strictness flag by flag, and measure what it catches before deciding to continue. Never mix migration with unrelated refactoring, replace any with unknown only to cast it back, or call it done because the compiler is quiet.
typeof, as const) or the other way, so they can't drift.tsc --extendedDiagnostics (instantiations, check time) before and after, rather than guessing.tsc --noEmit, tsc -b) and configuration, with the installed compiler, on the whole project the change affects. If the build only transpiles (Vite, esbuild, SWC), the type check is a separate step; make sure it still runs.@ts-expect-error cases or use the project's type-test tool.bezmoradi/knackpack
a52ee20
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.