typescript-magician

Overview of typescript-magician skill

What typescript-magician does

The typescript-magician skill helps you solve hard TypeScript problems that ordinary prompts handle poorly: deep generic design, strict typing cleanup, compiler errors, type guards, and advanced type transformations. It is most useful when the real job is not “write some TS,” but “make this API or codebase type-safe without breaking existing call sites.”

Best-fit use cases

Use the typescript-magician skill when you need help with any removal, infer, extends, conditional types, mapped types, template literal types, branded or opaque types, utility types, or inference bugs. It is a strong fit for code generation tasks where the output must be both ergonomic and type-correct, not just syntactically valid.

Why this skill is different

This skill is organized around compiler-first repair: capture tsc output, identify the root type issue, apply a precise fix, then verify the result compiles again. That makes typescript-magician more practical than a generic TypeScript prompt for teams that care about safety, refactoring confidence, and advanced type behavior.

How to Use typescript-magician skill

Install and activate it

Use the typescript-magician install flow from your skill manager, then point it at the repository where the TypeScript issue lives. The reference install command in the upstream skill is:

npx skills add mcollina/skills --skill typescript-magician

If your environment uses a different installer or workspace layout, keep the same intent: load the skill before asking it to modify types or diagnose a compiler error.

Give it a compiler-shaped task

The best typescript-magician usage starts with a concrete failure or a narrow goal. Good inputs include:

• a full tsc --noEmit error block
• the function, type, or file that is failing
• the desired runtime behavior and the desired type behavior
• any constraints such as “avoid as any,” “preserve public API,” or “support TS 5.x”

A strong prompt looks like:
“Fix this tsc --noEmit error without changing runtime behavior. Preserve the public API, remove the any, and keep inference for callers.”

Read these files first

For a practical typescript-magician guide, start with SKILL.md, then inspect rules/ for the pattern closest to your problem. The most useful entry points are usually:

• rules/error-diagnosis.md
• rules/generics-basics.md
• rules/conditional-types.md
• rules/type-narrowing.md
• rules/utility-types.md

If your issue is about runtime values feeding types, also check rules/as-const-typeof.md and rules/deep-inference.md.

Workflow that produces better output

First capture the exact error, then reduce the problem to the smallest failing type or function, then ask for a type-safe fix that keeps existing call sites working. For typescript-magician for Code Generation, include the target shape up front: expected generics, accepted input, returned type, and any edge cases like unions, nullable values, array indexing, or overloads.

typescript-magician skill FAQ

Is typescript-magician only for compiler errors?

No. The typescript-magician skill is also useful for designing types for new code, especially when you need advanced inference or reusable utility types. It becomes most valuable when types are part of the product contract, not just annotations.

When should I not use it?

Skip typescript-magician if the task is mainly runtime logic, formatting, or plain application code with no type-system complexity. It is also less useful if you cannot provide a real TypeScript error, file context, or acceptance criteria.

Is it beginner-friendly?

Yes, if you give it a narrow problem and let it explain the type reasoning in plain language. It is less beginner-friendly when the task depends on advanced conditional types or inference rules without any sample code.

How is it different from a normal TypeScript prompt?

A normal prompt often produces a plausible fix; typescript-magician is optimized to produce a fix that survives tsc, preserves call-site inference, and uses the right TypeScript feature for the job. That matters most in shared libraries, SDKs, and refactors where a “looks right” answer is not enough.

How to Improve typescript-magician skill

Provide the smallest failing example

The biggest quality boost comes from reducing the problem to the smallest reproducible TypeScript snippet. Include the type, the function signature, the failing call, and the compiler error. Smaller inputs make the typescript-magician skill more likely to choose the right constraint, overload, or conditional type.

State the constraints that matter

Tell the skill what it must preserve: runtime behavior, API shape, backward compatibility, strict mode, or support for older TS versions. If you want typescript-magician for Code Generation, also specify whether the output should prefer explicit helpers, inferred return types, or reusable generic utilities.

Watch for common failure modes

The most common misses are over-broad fixes that hide errors, any-based shortcuts, and type definitions that work for one example but break unions, arrays, or optional properties. If the first answer is too loose, ask for a stricter version and include one or two counterexamples that must still compile.

Iterate with real call sites

After the first fix, test it against representative usages: a union input, a nullable input, an array or tuple, and one “bad” input that should fail. Feed those results back into the typescript-magician guide prompt so the next pass can tighten inference instead of just patching the original error.