typescript-magician

Visão geral da skill typescript-magician

O que a typescript-magician faz

A skill typescript-magician ajuda a resolver problemas difíceis de TypeScript que prompts comuns lidam mal: desenho profundo de generics, limpeza de tipagem estrita, erros do compilador, type guards e transformações avançadas de tipos. Ela é especialmente útil quando o trabalho real não é “escrever um pouco de TS”, e sim “deixar esta API ou codebase type-safe sem quebrar os pontos de chamada existentes”.

Casos de uso ideais

Use a skill typescript-magician quando precisar de ajuda para remover any, usar infer, extends, conditional types, mapped types, template literal types, branded ou opaque types, utility types ou corrigir bugs de inference. Ela funciona muito bem em tarefas de geração de código em que a saída precisa ser ao mesmo tempo ergonômica e correta do ponto de vista de tipos, não apenas sintaticamente válida.

Por que esta skill é diferente

Esta skill é organizada em torno de correção guiada pelo compilador: capture a saída do tsc, identifique o problema raiz de tipos, aplique uma correção precisa e depois verifique se tudo compila novamente. Isso torna a typescript-magician mais prática do que um prompt genérico de TypeScript para equipes que se preocupam com segurança, confiança em refatoração e comportamento avançado do sistema de tipos.

Como usar a skill typescript-magician

Instale e ative

Use o fluxo typescript-magician install do seu gerenciador de skills e aponte para o repositório onde está o problema de TypeScript. O comando de instalação de referência na skill original é:

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

Se o seu ambiente usa outro instalador ou uma estrutura de workspace diferente, mantenha a mesma intenção: carregar a skill antes de pedir que ela altere tipos ou diagnostique um erro de compilador.

Dê a ela uma tarefa com cara de compilador

O melhor uso da typescript-magician começa com uma falha concreta ou um objetivo bem delimitado. Bons insumos incluem:

• um bloco completo de erro de tsc --noEmit
• a função, o type ou o arquivo que está falhando
• o comportamento desejado em runtime e o comportamento desejado em tipos
• qualquer restrição como “evite as any”, “preserve a API pública” ou “suporte TS 5.x”

Um prompt forte parece com isto:
“Corrija este erro de tsc --noEmit sem alterar o comportamento em runtime. Preserve a API pública, remova o any e mantenha a inferência para quem consome.”

Leia estes arquivos primeiro

Para um typescript-magician guide prático, comece por SKILL.md e depois inspecione rules/ em busca do padrão mais próximo do seu problema. Os pontos de entrada mais úteis costumam ser:

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

Se o seu problema envolver valores de runtime alimentando tipos, veja também rules/as-const-typeof.md e rules/deep-inference.md.

Fluxo de trabalho que gera resultados melhores

Primeiro capture o erro exato, depois reduza o problema ao menor type ou função que ainda falha, e então peça uma correção type-safe que mantenha os pontos de chamada existentes funcionando. Para typescript-magician for Code Generation, inclua logo no início a forma de saída desejada: generics esperados, entrada aceita, tipo retornado e quaisquer casos de borda como unions, valores nulos, indexação em arrays ou overloads.

FAQ da skill typescript-magician

A typescript-magician é só para erros de compilador?

Não. A skill typescript-magician também é útil para desenhar tipos para código novo, especialmente quando você precisa de inference avançada ou utility types reutilizáveis. Ela se torna mais valiosa quando os tipos fazem parte do contrato do produto, e não são apenas anotações.

Quando eu não deveria usá-la?

Evite a typescript-magician se a tarefa for principalmente lógica de runtime, formatação ou código de aplicação simples sem complexidade de type system. Ela também é menos útil quando você não consegue fornecer um erro real de TypeScript, contexto de arquivo ou critérios de aceitação.

Ela é amigável para iniciantes?

Sim, se você der um problema bem recortado e permitir que ela explique o raciocínio de tipos em linguagem simples. Ela fica menos amigável para iniciantes quando a tarefa depende de conditional types avançados ou regras de inference sem nenhum exemplo de código.

Como ela é diferente de um prompt normal de TypeScript?

Um prompt normal muitas vezes produz uma correção plausível; a typescript-magician é otimizada para produzir uma correção que passa pelo tsc, preserva a inferência nos pontos de chamada e usa o recurso certo de TypeScript para cada caso. Isso faz mais diferença em bibliotecas compartilhadas, SDKs e refatorações, onde uma resposta que “parece certa” não basta.

Como melhorar a skill typescript-magician

Forneça o menor exemplo que falha

O maior ganho de qualidade vem de reduzir o problema ao menor snippet reproduzível de TypeScript. Inclua o type, a assinatura da função, a chamada que falha e o erro do compilador. Entradas menores aumentam a chance de a skill typescript-magician escolher a constraint, overload ou conditional type correto.

Declare as restrições que importam

Diga à skill o que ela precisa preservar: comportamento em runtime, formato da API, compatibilidade retroativa, strict mode ou suporte a versões mais antigas do TS. Se quiser typescript-magician for Code Generation, especifique também se a saída deve preferir helpers explícitos, tipos de retorno inferidos ou utility types genéricos reutilizáveis.

Fique atento aos modos de falha mais comuns

Os erros mais frequentes são correções amplas demais que escondem problemas, atalhos baseados em any e definições de tipo que funcionam para um exemplo, mas quebram em unions, arrays ou propriedades opcionais. Se a primeira resposta vier frouxa demais, peça uma versão mais estrita e inclua um ou dois contraexemplos que ainda precisem compilar.

Itere com pontos de chamada reais

Depois da primeira correção, teste contra usos representativos: uma entrada union, uma entrada nullable, um array ou tuple e uma entrada “ruim” que deve falhar. Leve esses resultados de volta ao prompt do typescript-magician guide para que a próxima passada aperfeiçoe a inference em vez de apenas remendar o erro original.