CommunityEscrita e Ediçãogithub.com

swiftpostlabs/agentic-tools

Habilidades e ferramentas compartilháveis para agentes de IA

O que é agentic-tools?

Este skill fornece diretrizes abrangentes e configurações padrão para projetos modernos com Deno, especialmente em cenários que envolvem a integração com ferramentas orientadas ao Node.js ou a migração de padrões mais antigos do Deno. Ele ajuda os desenvolvedores a configurar `deno.json`, gerenciar dependências com `deno add`, e lidar com repositórios híbridos onde o código Deno coexiste com TypeScript ou Node. O skill documenta quando usar ferramentas nativas do Deno (como `deno lint` e `deno fmt`) versus ferramentas do ecossistema Node (como ESLint e `tsc`), e enfatiza a importância de permissões explícitas e configurações de segurança. É útil para qualquer pessoa que esteja adotando Deno em uma base de código existente ou construindo novos projetos que exigem uma separação clara entre os ambientes Deno e Node.

Funciona com~Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add swiftpostlabs/agentic-tools

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Deno

Propósito

Fornecer padrões portáteis para projetos modernos com Deno, especialmente quando a base de código mistura Deno com ferramentas orientadas ao Node, precisa de um caminho de migração limpo de padrões antigos do Deno, ou está adotando Deno em um repositório TypeScript ou Node existente.

Quando usar este skill

  • Escrevendo scripts, servidores ou código de borda com Deno.
  • Configurando deno.json, tarefas e fontes de dependência.
  • Adaptando tsconfig.json ou eslint.config.* existentes para coexistir com Deno.
  • Misturando código Deno com código Node ou TypeScript em um único repositório.
  • Revisando permissões, testes ou padrões de tempo de execução do Deno.

Padrões

  • Use deno.json como a fonte de verdade do Deno.
  • Prefira deno check, deno task, deno fmt, deno lint e deno test em vez de wrappers ad hoc quando o Deno for o dono do fluxo de trabalho.
  • As ferramentas nativas do Deno são suficientes para código de propriedade do Deno; use Yarn apenas quando o repositório também tiver pacotes gerenciados pelo Node ou scripts fora do limite do Deno.
  • Mantenha tsconfig.json apenas para caminhos de propriedade do Node ou para casos de gráfico de projeto TypeScript que espaços de trabalho e escopos de diretório do Deno não conseguem expressar de forma limpa.
  • Lembre-se de que o Node moderno também executa TypeScript diretamente através da remoção de tipos integrada; escolha Deno pelo seu modelo de tempo de execução, permissões, dependência e ferramentas, não apenas para evitar tsc ou ts-node.
  • Prefira deno lint e deno fmt para arquivos de propriedade do Deno; adicione ESLint apenas quando o repositório ou editor realmente precisar do ecossistema ESLint.
  • Ao substituir ESLint por deno lint, inspecione e leve adiante a intenção existente do ESLint para includes, excludes, regras de lint ou exceções documentadas em deno.json, em vez de descartar a configuração por completo.
  • Ao substituir tsc por deno check, inspecione o tsconfig.json existente e traduza opções de compilador, includes, excludes, libs e expectativas de rigor relevantes para deno.json ou um tsconfig.json retido com escopo claramente definido.
  • Quando ferramentas de editor baseadas em npm, como ESLint, precisarem ser executadas dentro de um repositório Deno, defina nodeModulesDir: "auto" e envolva o comando em deno task.
  • Quando o Deno for o dono do gerenciamento de dependências, instale dependências com deno add, não tratando deno run npm:<package> como substituto para instalação. Use deno add --dev npm:<package> para CLIs e ferramentas de desenvolvimento.
  • Para ferramentas CLI instaladas, nomeie a deno task com o nome da ferramenta e invoque o binário instalado pelo nome, por exemplo, após deno add --dev npm:sample-tool, adicione "sample-tool": "sample-tool".
  • Prefira módulos .ts por padrão em código de propriedade do Deno; não recorra a JavaScript apenas para evitar uma etapa de build que o Deno não exige.
  • Prefira pacotes JSR, especificadores npm: ou entradas de mapa de importação explícitas em vez de importações de URL legadas espalhadas.
  • Quando um CLI baseado em npm tiver comportamento de instalação ou pós-instalação que não coopera de forma limpa com execução única, prefira nodeModulesDir: "auto", permita o pacote em allowScripts, adicione a dependência com deno add ou deno add --dev, e invoque o binário instalado a partir de uma deno task.
  • O Deno 2 é intencionalmente compatível com package.json, pacotes npm e built-ins do Node; mantenha a configuração específica do Deno em deno.json em vez de tentar fazer tsconfig.json carregar ambos os mundos.
  • Prefira APIs padrão da Web e Deno.serve para servidores.
  • Trate permissões como uma decisão de design, não um pensamento posterior.

Enquadramento de Tarefas

Comando ou açãoO quêPor quêQuandoResultado esperado
Adotar tsconfig.json e ESLint com cuidadoDecidir o que fica na configuração de propriedade do Node e o que vai para deno.json.Repositórios híbridos ficam barulhentos rapidamente quando ambas as toolchains tentam ser donas dos mesmos arquivos.Ao introduzir o Deno em uma base de código TypeScript ou Node existente.Ferramentas Deno e Node têm limites de propriedade explícitos.
Configurar deno.jsonDefinir tarefas, opções de compilador e convenções de dependência no arquivo de configuração do Deno.O Deno deve ser dono do seu próprio fluxo de trabalho, em vez de pegar emprestada uma configuração centrada no Node por acidente.Ao iniciar ou reestruturar um projeto Deno.Comandos Deno e comportamento do editor são consistentes.
Instalar um CLI npm de propriedade do DenoExecute deno add --dev npm:<package> para ferramentas de desenvolvimento, depois adicione uma tarefa com o mesmo nome que invoca o binário instalado.A dependência, o lockfile, o binário local e o ponto de entrada da tarefa permanecem alinhados sob o gerenciador de pacotes do Deno.Ao adicionar ferramentas como geradores de código, CLIs de automação de navegador, linters ou formatadores a um fluxo de trabalho de propriedade do Deno.deno.json e o lockfile registram a dependência, e deno task <tool> executa o CLI instalado.
Definir limites híbridosSeparar caminhos de propriedade do Deno de caminhos de propriedade do Node em repositórios mistos.Conflitos de ferramentas são uma das falhas mais comuns em repositórios híbridos.Quando o código Deno está ao lado de ferramentas Node ou TS.Editores e comandos não disputam os mesmos arquivos.
Revisar permissõesEscolher flags --allow-* explícitas ou conjuntos de permissões nomeados em deno.json.O modelo de segurança do Deno só ajuda quando as permissões são deliberadas.Antes de executar novos scripts ou expor um fluxo de trabalho CLI do Deno.O acesso a sistema de arquivos, rede e ambiente é intencional e auditável.
Solucionar problemas de fluxos de trabalho do DenoUsar verificações nativas do Deno, flags de depuração e ferramentas de gráfico de módulo antes de adivinhar.Muitos problemas com Deno são de configuração, permissão ou propriedade, não bugs de código.Quando um repositório híbrido ou toolchain migrada se comporta inesperadamente.A causa raiz é reduzida a configuração, permissões ou comportamento de tempo de execução.

Regras Principais

TypeScript, tsconfig.json e bibliotecas

  • Coloque configurações de compilador do Deno em deno.json sob compilerOptions; não copie um tsconfig.json inteiro do Node apenas para fazer deno check funcionar.
  • Espaços de trabalho existentes do Node mais TypeScript podem manter tsconfig.json; o Deno o consulta quando um diretório também contém deno.json ou package.json.
  • Se um deno.json pai define compilerOptions, essas opções têm precedência sobre opções sobrepostas de tsconfig.json.
  • Se o objetivo é substituir tsc, primeiro faça um inventário do comportamento atual do tsconfig.json. Preserve decisões significativas de rigor, resolução de módulo, JSX, biblioteca, include e exclude na configuração do Deno ou documente por que elas não se aplicam mais.
  • Use compilerOptions.lib em deno.json para modelar a superfície de tempo de execução real. Para SSR ou código de navegador mais Deno, prefira combinações como ["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]; para workers Deno, prefira ["deno.worker"].
  • Use compilerOptions.checkJs, // @ts-check, @ts-types, @ts-self-types ou compilerOptions.types quando módulos JavaScript precisarem de verificação de tipo ou declarações explícitas.
  • Mantenha tsconfig.json apenas quando pastas de propriedade do Node, referências de projeto TS ou granularidade de include ou exclude ainda exigirem.

Linting, formatação e ESLint

  • Use deno lint e a seção lint em deno.json como o proprietário padrão de linting para código de propriedade do Deno.
  • Use deno fmt e a seção fmt em deno.json como o formatador padrão para código de propriedade do Deno.
  • deno lint já cobre um conjunto de regras recomendado inspirado no ESLint; não mantenha ESLint apenas por hábito.
  • Se o objetivo é substituir ESLint, primeiro faça um inventário do comportamento atual de eslint.config.*. Preserve escopos de arquivo, globais, ignores e intenção de regras significativos na configuração de lint/fmt do Deno ou documente quais regras são intencionalmente descartadas porque o Deno já as cobre ou rejeita.
  • Se regras personalizadas exclusivas do Deno forem necessárias, considere lint.plugins; note que a API de plugin de lint é experimental e requer Deno 2.2 ou superior.
  • Se o repositório ou editor ainda precisar de ESLint, torne-o uma ferramenta secundária explícita: defina nodeModulesDir: "auto", crie eslint.config.js e envolva a invocação em deno task, por exemplo deno task eslint.
  • Mantenha um proprietário de lint por conjunto de arquivos sempre que possível. Se ambos deno lint e ESLint forem executados nos mesmos arquivos, documente o porquê ou espere diagnósticos duplicados e conflitantes.

Compatibilidade com Node e repositórios híbridos

  • O Deno 2 entende package.json, node_modules, espaços de trabalho npm e built-ins do Node; repositórios híbridos são um caminho suportado, não uma gambiarra.
  • O Node moderno também pode executar TypeScript diretamente. Em repositórios híbridos, decida a propriedade Node versus Deno por permissões, modelo de dependência, executor de tarefas e destino de implantação, não apenas pela execução de TypeScript.
  • Se um package.json existir e você quiser que o Deno crie e atualize automaticamente node_modules, defina nodeModulesDir: "auto". Com package.json, o Deno 2, caso contrário, usa o padrão "manual".
  • nodeModulesDir é uma configuração de raiz do espaço de trabalho; não tente defini-la por membro do espaço de trabalho.
  • Use deno install ou deno add quando o Deno for o dono do fluxo de atualização de dependências. Não assuma o comportamento de auto-instalação do Deno 1.
  • Use deno add --dev npm:<package> para CLIs npm exclusivos de desenvolvimento em repositórios de propriedade do Deno. Após a adição, exponha o binário através de uma deno task, como "sample-tool": "sample-tool" em vez de "sample-tool": "deno run -A npm:sample-tool".
  • Faça commit das atualizações de manifesto e lockfile produzidas por deno add; um alias de tarefa sozinho não é uma instalação de dependência.
  • Não habilite ferramentas Deno para um espaço de trabalho misto inteiro se apenas uma subárvore for Deno.
  • Prefira ativação de editor baseada em caminho, como deno.enablePaths, para que as ferramentas Node e Deno não disputem os mesmos arquivos.
  • Mantenha o limite do Deno explícito na estrutura de pastas, tarefas e docs.

Permissões, ambiente e segurança

  • Prefira flags --allow-* específicas conjuntos de permissões nomeados em deno.json em vez de -A.
  • Use -P ou --permission-set=<nome> quando o repositório definir conjuntos de permissões em deno.json.
  • Use --env-file quando o CLI deve carregar arquivos .env, ou @std/dotenv quando o próprio programa precisar carregá-los; ambos ainda precisam de permissões explícitas de ambiente e arquivo.
  • Prefira privilégio mínimo para código de aplicação e mantenha o acesso a ambiente, sistema de arquivos, rede e subprocessos óbvio em tarefas e exemplos.
  • Trate --allow-run e --allow-ffi como portas de escape do sandbox. Evite --allow-run=deno a menos que confiança total seja intencionalmente pretendida.
  • Para depuração ou auditoria de permissões, use DENO_TRACE_PERMISSIONS=1 e DENO_AUDIT_PERMISSIONS=<caminho>.

Solução de problemas e migração

  • Recorra a deno check, deno check --all ou deno run --check quando o sucesso em tempo de execução e o comportamento de verificação de tipo divergirem.
  • Use deno info <entrypoint> para inspecionar o gráfico de módulo e entender o comportamento de importação, cache e permissão.
  • Use deno lint --fix para limpeza comum de migração antes de editar manualmente cada problema de lint.
  • Para configuração de depurador, use --inspect-brk quando o processo for de curta duração, --log-level=debug quando o inspetor ou a resolução de módulo estiver confuso, e --strace-ops quando o tempo de execução estiver travado ou inesperadamente lento.
  • Use flags de perfil de CPU como --cpu-prof, --cpu-prof-md ou --cpu-prof-flamegraph quando a questão de solução de problemas for realmente sobre desempenho.
  • O conselho de migração deve refletir os padrões do Deno 2: nodeModulesDir agora usa "none" | "auto" | "manual", deno cache tornou-se deno install --entrypoint, deno vendor tornou-se "vendor": true, Deno.run() deve se tornar new Deno.Command(), e Deno.serveHttp() deve se tornar Deno.serve().
  • Use atributos de importação como with { type: "json" } em vez de asserções de importação obsoletas.

Peculiaridades

  • Se as ferramentas Deno e Node reivindicarem os mesmos arquivos, os diagnósticos do editor se tornam barulhentos e enganosos.
  • Se package.json existir, o Deno 2 usa o padrão nodeModulesDir como "manual"; esquecer disso é uma razão comum para ferramentas baseadas em npm parecerem meio instaladas.
  • Se a extensão ESLint do VS Code fizer parte do fluxo de trabalho, ela não resolverá pacotes apenas do cache global do Deno; ela precisa de um diretório node_modules local.
  • deno run pula a verificação de tipo por padrão, então uma execução bem-sucedida não é evidência de que deno check passará.
  • Uma deno task que chama deno run npm:<package> é um atalho de execução única, não uma instalação de dependência adequada. Não use isso como a resposta padrão para "instalar e configurar este CLI" em um repositório de propriedade do Deno.
  • -A é aceitável para ferramentas confiáveis, mas é o padrão errado para código de aplicação comum.
  • Alguns CLIs npm, incluindo Supabase em repositórios reais de tempo de execução misto, dependem de comportamento em tempo de instalação que pode ser menos confiável através de deno run npm:... do que através de um binário instalado em node_modules.
  • Padrões antigos de importação de URL e ativação de espaço de trabalho inteiro são auxílios de transição, não padrões modernos.

Validação

  • deno.json é o dono da configuração e tarefas do Deno.
  • Qualquer tsconfig.json retido ou propriedade do ESLint é explícito e escopado aos arquivos corretos.
  • Substituir ESLint ou tsc preserva o comportamento útil da configuração existente ou documenta por que foi intencionalmente descartado.
  • As partes Deno e Node de um repositório híbrido não disputam ferramentas.
  • Especificadores de dependência são modernos e explícitos.
  • CLIs npm de propriedade do Deno são adicionados com deno add ou deno add --dev, registrados no manifesto e lockfile, e executados através de tarefas que invocam nomes de binários instalados.
  • nodeModulesDir, ativação de editor e quaisquer ferramentas Deno baseadas em npm são configurados intencionalmente.
  • Se um CLI npm é acionado a partir de tarefas Deno, o repositório configura intencionalmente nodeModulesDir e allowScripts em vez de depender de efeitos colaterais acidentais de instalação.
  • Permissões são intencionais e documentadas onde importam.
  • A orientação de solução de problemas começa com verificações nativas do Deno antes de recorrer a conselhos genéricos de depuração Node ou TypeScript.

Referências

[truncated for translation]

Habilidades Relacionadas