typescript-magician

typescript-magician skill の概要

typescript-magician ができること

typescript-magician skill は、普通のプロンプトでは対応しづらい難度の高い TypeScript 問題を解くための skill です。たとえば、深いジェネリック設計、厳密な型付けの整理、コンパイラエラーの解消、type guard、高度な型変換などに向いています。特に、「TS を何か書く」のではなく、「既存の呼び出し元を壊さずに、この API やコードベースを type-safe にしたい」という場面で真価を発揮します。

最適な用途

any の排除、infer、extends、conditional types、mapped types、template literal types、branded または opaque types、utility types、推論バグの解消を手伝ってほしいときに、typescript-magician skill を使ってください。単に構文的に正しいだけでなく、使いやすくて型としても正しいコード生成が必要なタスクに強く適しています。

この skill が違う理由

この skill は compiler-first の修復フローを中心に構成されています。つまり、まず tsc の出力を取り、根本の型問題を特定し、的確な修正を加え、最後に再びコンパイルできることを確認します。そのため、typescript-magician は、安全性、リファクタリング時の安心感、高度な型の挙動を重視するチームにとって、汎用的な TypeScript プロンプトより実用的です。

typescript-magician skill の使い方

インストールして有効化する

まず skill manager から typescript-magician install の流れで導入し、対象の TypeScript 問題があるリポジトリを指定してください。上流 skill にある参考インストールコマンドは次のとおりです。

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

環境によって installer や workspace の構成が違う場合でも、意図は同じです。型を変更したり compiler error を診断したりする前に、先にこの skill を読み込んでください。

コンパイラ前提の課題として渡す

typescript-magician usage で最も良い結果が出るのは、具体的な失敗、または範囲の狭いゴールから始めたときです。よい入力例は次のとおりです。

• tsc --noEmit のエラーブロック全文
• 失敗している function、type、または file
• 望ましい runtime behavior と type behavior
• as any を避ける、public API を維持する、TS 5.x をサポートする、などの制約

強いプロンプトの例は次のようになります。
「runtime behavior は変えずに、この tsc --noEmit エラーを直してください。public API は維持し、any を削除し、呼び出し元の inference は保ってください。」

まず読むべき file

実用的な typescript-magician guide としては、まず SKILL.md を読み、そのあと問題に最も近いパターンがある rules/ を確認してください。特に役立つ入口はたいてい次のとおりです。

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

runtime の値が type に流れ込む問題なら、rules/as-const-typeof.md と rules/deep-inference.md も確認してください。

よい出力につながる進め方

まず正確な error を取り、次に問題を最小の failing type か function まで縮小し、そのうえで既存の呼び出し元が動き続ける type-safe な修正を依頼します。typescript-magician for Code Generation では、最初に target shape を明示してください。必要な generics、受け付ける input、返す type、そして union、nullable 値、配列 index、overload のような edge case まで含めると精度が上がります。

typescript-magician skill の FAQ

typescript-magician は compiler error 専用ですか？

いいえ。typescript-magician skill は、新しいコードの type 設計にも役立ちます。特に、高度な inference や再利用可能な utility types が必要なときに有効です。型が単なる注釈ではなく、製品としての契約の一部になっているときに最も価値を発揮します。

使わないほうがよいのはどんなときですか？

主に runtime ロジック、書式調整、あるいは type-system の複雑さがない通常の application code が目的なら、typescript-magician は使わなくて構いません。また、実際の TypeScript error、file context、acceptance criteria を提示できない場合も、効果は下がります。

初心者向けですか？

はい。問題を狭く切り出し、型の考え方を平易な言葉で説明してもらうなら、初心者にも使いやすいです。一方で、advanced conditional types や inference rules に依存するのに、サンプルコードがない課題では、初心者向けとは言いにくくなります。

通常の TypeScript プロンプトと何が違いますか？

通常のプロンプトは見た目として妥当な修正を返すことが多いですが、typescript-magician は tsc を通り、呼び出し元の inference を保ち、用途に合った TypeScript feature を使う修正を出すことに最適化されています。特に、共有ライブラリ、SDK、リファクタリングのように、「見た目が正しそう」では足りない場面で差が出ます。

typescript-magician skill を改善するには

失敗する最小例を渡す

品質を最も大きく上げるのは、問題を最小の再現可能な TypeScript snippet まで縮小することです。type、function signature、失敗する呼び出し、compiler error を含めてください。入力が小さいほど、typescript-magician skill は適切な constraint、overload、conditional type を選びやすくなります。

重要な制約を明示する

何を守るべきかを伝えてください。たとえば runtime behavior、API shape、後方互換性、strict mode、古い TS バージョンのサポートなどです。typescript-magician for Code Generation を使うなら、明示的な helper を優先するのか、推論された return type を優先するのか、再利用可能な generic utility を優先するのかも指定してください。

よくある失敗パターンに注意する

よくあるミスは、エラーを隠してしまう広すぎる修正、any に頼る回避策、ひとつの例では動くのに union、array、optional property で壊れる type definition です。最初の回答がゆるすぎる場合は、より厳密な版を求め、なお compile できるべき反例を 1 つか 2 つ追加してください。

実際の呼び出し元で反復する

最初の修正のあと、代表的な使い方で試してください。たとえば union input、nullable input、array または tuple、そして失敗すべき「bad」input です。その結果を typescript-magician guide の prompt に戻すと、次の修正では元のエラーを場当たり的に直すのではなく、inference をより厳密にできます。