search-first

Visão geral do skill search-first

O que é search-first

O skill search-first é um fluxo de trabalho de pesquisar antes de codar, usado para encontrar ferramentas, bibliotecas e padrões de implementação existentes antes de escrever código customizado. Ele é útil quando você quer que o assistente atue como um explorador cuidadoso, e não como alguém que sai codando no chute.

Quem deve usar

Use o skill search-first se você estiver começando uma nova funcionalidade, avaliando uma dependência, adicionando uma integração ou construindo um helper que talvez já exista. Ele também encaixa muito bem no caso de uso search-first for Skill Scaffolding quando você quer reaproveitar padrões já comprovados em vez de inventar um novo.

Por que isso importa

O principal valor do search-first está na qualidade da decisão: ele leva o assistente a pesquisar em npm, PyPI, GitHub, fontes da web e skills relacionadas antes de recomendar código. Isso reduz retrabalho, melhora a escolha de dependências e deixa decisões de “build vs adopt vs wrap” muito mais bem fundamentadas.

Como usar o skill search-first

Instale e acione o skill

Para search-first install, adicione o skill com npx skills add affaan-m/everything-claude-code --skill search-first. Acione-o quando a tarefa soar como “adicionar X”, “encontrar uma biblioteca para Y” ou “já existe uma forma melhor de fazer isso?”. O padrão search-first usage funciona melhor quando você pede explicitamente pesquisa antes da implementação.

Dê um briefing orientado à decisão

Um briefing fraco diz “construa um parser de arquivos”. Um briefing mais forte diz: “Preciso de um parser de arquivos TypeScript para Node 18, precisa suportar streaming, sem dependências nativas, licença MIT preferida, e quero 3 opções de adotar ou construir, com trade-offs.” Esse formato dá contexto suficiente para o skill pesquisar bem e comparar candidatos, em vez de devolver sugestões genéricas.

Leia primeiro os arquivos certos

Comece com SKILL.md, depois confira README.md, AGENTS.md, metadata.json e quaisquer pastas rules/, resources/, references/ ou scripts/, se existirem. Neste repositório, SKILL.md é a principal fonte de verdade, então você pode avançar rápido sem ficar caçando arquivos de apoio.

Use o fluxo como um template de prompt

Um prompt prático de search-first guide deve pedir: a necessidade, as restrições, a busca por candidatos, os critérios de avaliação e uma decisão clara. Exemplo: “Pesquise opções existentes para X, compare 3 candidatos, pontue-os em manutenção, documentação, licença e aderência, e então recomende adotar, estender ou construir sob medida.” Essa estrutura ajuda o agente pesquisador a entregar algo utilizável, em vez de uma lista solta.

FAQ do skill search-first

O search-first é só para projetos grandes?

Não. Muitas vezes ele é ainda mais valioso em tarefas pequenas que podem criar dívida técnica silenciosa, como uma função helper, uma utilidade de UI ou a escolha de uma dependência. O custo de pular a pesquisa costuma ser maior justamente quando a mudança parece simples.

Em que ele é diferente de um prompt comum?

Um prompt comum pode pedir ideias; o search-first skill pede um fluxo de pesquisa e uma decisão. Essa diferença importa porque o resultado é feito para apoiar decisões de adoção, e não apenas responder “o que eu poderia codar?”.

Ele é amigável para iniciantes?

Sim, desde que você consiga descrever seu objetivo e suas restrições. Iniciantes se beneficiam porque o skill reduz o espaço de busca e traz à tona opções existentes que talvez eles nem soubessem que deveriam procurar. Ele é menos útil se você quer código instantâneo sem análise de trade-offs.

Quando eu não deveria usar?

Evite quando a tarefa for obviamente customizada, extremamente urgente ou muito específica do seu código, sem que uma solução externa faça sentido. Se você já sabe exatamente qual pacote ou padrão quer, uma implementação direta pode ser mais rápida do que uma pesquisa completa.

Como melhorar o skill search-first

Informe restrições que realmente mudam a busca

O maior ganho de qualidade vem de nomear as restrições difíceis desde o início: linguagem, runtime, framework, licença, tamanho do bundle, regras de segurança, limites de plataforma e se dependências nativas são permitidas. Esses detalhes ajudam o skill a filtrar candidatos, em vez de trazer opções populares, mas inutilizáveis.

Peça comparações, não só recomendações

Uma solicitação melhor de search-first usage pede uma shortlist curta e uma recomendação com justificativa. Por exemplo: “Compare 3 bibliotecas, explique por que cada uma pode falhar e depois escolha uma para produção e uma como plano B.” Isso gera pesquisa mais acionável do que uma resposta com um único nome.

Cuidado com o viés de novidade superficial

Uma falha comum é escolher o projeto mais novo ou mais visível sem verificar manutenção, documentação ou custo de integração. Melhore o search-first skill pedindo que ele inclua fricção de adoção, compatibilidade com o ecossistema e o que faria você rejeitar um candidato.

Itere depois da primeira passada

Se o primeiro resultado vier amplo demais, refine o próximo prompt com uma restrição que faltou ou com um teste de aceitação. Para search-first for Skill Scaffolding, isso pode significar adicionar a linguagem-alvo, a estrutura do repositório ou o tipo exato de scaffold que você quer reaproveitar.