typescript-magician

Tổng quan về skill typescript-magician

typescript-magician làm gì

Skill typescript-magician giúp bạn xử lý các bài toán TypeScript khó mà prompt thông thường thường không giải quyết tốt: thiết kế generic phức tạp, dọn dẹp kiểu chặt chẽ, lỗi compiler, type guards và các phép biến đổi type nâng cao. Skill này hữu ích nhất khi công việc thực sự không phải là “viết vài dòng TS,” mà là “làm cho API hoặc codebase này an toàn kiểu mà không phá vỡ các call site hiện có.”

Trường hợp sử dụng phù hợp nhất

Hãy dùng skill typescript-magician khi bạn cần hỗ trợ với việc loại bỏ any, infer, extends, conditional types, mapped types, template literal types, branded hoặc opaque types, utility types, hay các lỗi inference. Đây cũng là lựa chọn mạnh cho những tác vụ sinh code mà đầu ra phải vừa dễ dùng vừa đúng kiểu, chứ không chỉ hợp lệ về cú pháp.

Điều gì khiến skill này khác biệt

Skill này được tổ chức theo hướng sửa lỗi từ compiler trước hết: chụp output của tsc, xác định đúng nguyên nhân gốc ở tầng type, áp dụng một sửa lỗi chính xác, rồi xác minh lại để chắc chắn compile thành công. Cách làm này khiến typescript-magician thực dụng hơn một prompt TypeScript chung chung, đặc biệt với các đội ngũ coi trọng an toàn, tự tin khi refactor và hành vi type nâng cao.

Cách dùng skill typescript-magician

Cài đặt và kích hoạt

Dùng luồng typescript-magician install từ skill manager của bạn, rồi trỏ nó vào repository đang chứa lỗi TypeScript. Lệnh cài đặt tham chiếu trong skill gốc là:

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

Nếu môi trường của bạn dùng bộ cài khác hoặc cấu trúc workspace khác, hãy giữ đúng mục tiêu: nạp skill trước khi yêu cầu nó sửa type hoặc chẩn đoán lỗi compiler.

Đưa cho nó một nhiệm vụ mang hình dạng của compiler

Cách dùng typescript-magician usage tốt nhất luôn bắt đầu bằng một lỗi cụ thể hoặc một mục tiêu hẹp. Input tốt gồm:

• một khối lỗi đầy đủ từ tsc --noEmit
• function, type hoặc file đang lỗi
• hành vi runtime mong muốn và hành vi type mong muốn
• mọi ràng buộc như “tránh as any,” “giữ nguyên public API,” hoặc “hỗ trợ TS 5.x”

Một prompt mạnh có thể như sau:
“Fix lỗi tsc --noEmit này mà không đổi hành vi runtime. Giữ nguyên public API, bỏ any, và vẫn giữ inference cho caller.”

Đọc trước các file này

Với một typescript-magician guide thực dụng, hãy bắt đầu từ SKILL.md, rồi xem rules/ để tìm pattern gần nhất với vấn đề của bạn. Các điểm vào hữu ích nhất thường là:

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

Nếu vấn đề của bạn liên quan đến giá trị runtime nuôi type, hãy kiểm tra thêm rules/as-const-typeof.md và rules/deep-inference.md.

Quy trình cho đầu ra tốt hơn

Trước hết hãy chốt lỗi chính xác, sau đó thu gọn bài toán về type hoặc function nhỏ nhất đang fail, rồi yêu cầu một bản sửa an toàn về kiểu nhưng vẫn giữ cho call site hiện có hoạt động. Với typescript-magician for Code Generation, hãy nêu rõ ngay từ đầu hình dạng đầu ra mong muốn: generic nào, input nào được chấp nhận, type trả về là gì, và các trường hợp biên như union, giá trị nullable, truy cập mảng theo chỉ số, hay overload.

Câu hỏi thường gặp về skill typescript-magician

typescript-magician chỉ dành cho lỗi compiler thôi à?

Không. Skill typescript-magician cũng hữu ích khi thiết kế type cho code mới, nhất là lúc bạn cần inference nâng cao hoặc các utility type có thể tái sử dụng. Nó trở nên giá trị nhất khi type là một phần của hợp đồng sản phẩm, chứ không chỉ là chú thích.

Khi nào thì không nên dùng?

Hãy bỏ qua typescript-magician nếu bài toán chủ yếu là logic runtime, định dạng, hoặc code ứng dụng thuần túy mà không có độ phức tạp về type system. Skill này cũng kém hữu ích hơn nếu bạn không thể cung cấp lỗi TypeScript thật, ngữ cảnh file, hoặc tiêu chí chấp nhận rõ ràng.

Skill này có thân thiện với người mới không?

Có, nếu bạn đưa ra một bài toán hẹp và để nó giải thích lý do về type bằng ngôn ngữ dễ hiểu. Nó sẽ kém thân thiện hơn với người mới khi nhiệm vụ phụ thuộc vào conditional types nâng cao hoặc quy tắc inference mà không có sample code.

Nó khác gì so với một prompt TypeScript bình thường?

Một prompt bình thường thường tạo ra một bản sửa hợp lý; typescript-magician được tối ưu để tạo ra bản sửa vượt qua tsc, giữ nguyên inference ở call site, và dùng đúng tính năng TypeScript cho đúng việc. Điều này quan trọng nhất trong shared library, SDK, và các đợt refactor mà một câu trả lời “trông có vẻ đúng” là chưa đủ.

Cách cải thiện skill typescript-magician

Đưa ra ví dụ lỗi nhỏ nhất

Cách tăng chất lượng mạnh nhất là rút bài toán về snippet TypeScript nhỏ nhất có thể tái hiện lỗi. Hãy bao gồm type, chữ ký function, lời gọi đang lỗi, và thông báo compiler. Input càng nhỏ thì skill typescript-magician càng dễ chọn đúng constraint, overload, hoặc conditional type.

Nêu rõ các ràng buộc quan trọng

Hãy nói rõ skill phải giữ lại điều gì: hành vi runtime, hình dạng API, backward compatibility, strict mode, hay hỗ trợ các phiên bản TS cũ hơn. Nếu bạn muốn typescript-magician for Code Generation, hãy chỉ rõ đầu ra nên ưu tiên helper tường minh, return type được inference, hay reusable generic utilities.

Cảnh giác với các kiểu lỗi thường gặp

Những lỗi hay gặp nhất là bản sửa quá rộng làm che mất lỗi, shortcut dựa trên any, và type definition chạy tốt cho một ví dụ nhưng vỡ với union, array, hoặc optional properties. Nếu câu trả lời đầu tiên quá lỏng, hãy yêu cầu một phiên bản chặt hơn và đưa vào một hoặc hai phản ví dụ vẫn phải compile.

Lặp lại với call site thực tế

Sau bản sửa đầu tiên, hãy thử nó với các cách dùng đại diện: input dạng union, input nullable, một array hoặc tuple, và một input “xấu” đáng lẽ phải fail. Đưa các kết quả đó trở lại prompt typescript-magician guide để lượt tiếp theo có thể siết chặt inference thay vì chỉ vá lỗi ban đầu.