Communitygithub.com

ASoudy/AGS

Esta habilidade deve ser usada para realizar pesquisas abrangentes sobre qualquer tópico utilizando a API OpenAI Deep Research. Ela automatiza o aprimoramento de prompts por meio de perguntas de esclarecimento interativas, salva parâmetros de pesquisa e executa pesquisas profundas com recursos de busca na web. Use quando o usuário solicitar análises aprofundadas, investigações, resumos de pesquisa ou exploração de tópicos.

O que é AGS?

A habilidade Deep Research é uma ferramenta de automação de pesquisa impulsionada por IA, projetada para orquestrar pesquisas abrangentes na web usando a API de Pesquisa Profunda da OpenAI (modelo o4-mini-deep-research). Ela é útil para desenvolvedores e agentes de IA que precisam de análises aprofundadas, investigações ou resumos de tópicos de forma eficiente. Suporta plataformas baseadas em linha de comando, como Claude Code, Cursor e Codex, onde scripts Python e variáveis de ambiente são suportados. A habilidade funciona analisando automaticamente a integridade do prompt do usuário, fazendo perguntas de esclarecimento para refinar consultas breves e, em seguida, executando a pesquisa com parâmetros salvos para reprodutibilidade. O fluxo de trabalho é otimizado para eficiência de tokens, executando de forma síncrona (bloqueante) sem verificações de status intermediárias, economizando tokens durante o período de pesquisa de 10 a 20 minutos. Os resultados incluem um relatório detalhado em markdown com fontes, salvo em arquivos com timestamp. Recursos como detecção inteligente de tópicos técnicos vs. gerais, perguntas de modelo personalizáveis e opções de linha de comando flexíveis a tornam ideal para pesquisas técnicas, tendências de mercado e estudos comparativos.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/claude_skills_libraries/landing-page-mastery/skills/deep-research

Perguntar na sua IA favorita

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

Documentação

Habilidade de Pesquisa Profunda

Propósito

Esta habilidade permite pesquisas abrangentes e habilitadas para internet sobre qualquer tópico usando a API de Pesquisa Profunda da OpenAI (modelo o4-mini-deep-research). Ela aprimora de forma inteligente os prompts de pesquisa do usuário por meio de perguntas de esclarecimento interativas, garante que os parâmetros de pesquisa sejam salvos para reprodutibilidade e executa pesquisas profundas com recursos completos de busca na web.

Quando Usar Esta Habilidade

Ative esta habilidade quando:

  • O usuário solicitar pesquisa sobre um tópico específico
  • O usuário pedir análise, investigação ou coleta abrangente de informações
  • O usuário quiser explorar um assunto com busca na web e raciocínio
  • O usuário fornecer uma consulta de pesquisa breve que possa ser refinada
  • O usuário quiser entender o estado atual, tendências ou comparações em uma área

Exemplos de solicitações de usuário:

  • "Pesquise as soluções RAG de código aberto mais eficazes com alto desempenho em benchmarks"
  • "Quais são os últimos desenvolvimentos de IA em 2025?"
  • "Preciso de uma análise abrangente de sistemas de banco de dados distribuídos"
  • "Encontre melhores práticas para implementar busca vetorial"
  • "Investigue como a IA está impactando a indústria de engenharia de software"

Visão Geral do Fluxo de Trabalho

Entrada do Usuário
    ↓
Avaliação: Prompt muito breve?
    ↓
SIM → Fazer Perguntas de Esclarecimento → Coletar Respostas
    ↓                               ↓
    └───────→ Construir Prompt Aprimorado ←──┘
                    ↓
            Salvar em Arquivo com Timestamp
                    ↓
            Executar deep_research.py
                    ↓
            Relatório de Saída + Fontes
                    ↓
            Apresentar ao Usuário

Como o Claude Deve Usar Esta Habilidade

Importante para Eficiência de Tokens: A pesquisa profunda leva de 10 a 20 minutos para ser concluída. A habilidade foi projetada para ser executada de forma síncrona (bloqueante) sem verificações de status intermediárias. Essa abordagem minimiza o uso de tokens durante a espera. Claude deve:

  1. Iniciar a pesquisa
  2. Aguardar a conclusão (o subprocesso bloqueia automaticamente)
  3. Apresentar os resultados finais assim que concluído

Não é necessário fazer polling periódico ou atualizações de status durante a execução.

Etapa 1: Aceitar a Solicitação de Pesquisa

Receba o prompt de pesquisa do usuário. Isso pode variar de breve ("Últimas tendências de IA") a altamente detalhado ("Impacto dos modelos de linguagem na produtividade do desenvolvedor com foco em 2024-2025").

Etapa 2: Executar o Script de Orquestração

Execute o script principal de orquestração da habilidade com o prompt de pesquisa do usuário:

python3 scripts/run_deep_research.py "Seu prompt de pesquisa aqui"

O script está localizado em scripts/run_deep_research.py dentro da instalação da habilidade.

Etapa 3: Fluxo de Execução do Script

O script automaticamente:

  1. Avalia a completude do prompt: Verifica se o prompt é muito breve ou genérico (< 15 palavras ou começa com "o que é", "como", etc.)

  2. Faz perguntas de esclarecimento (se necessário):

    • Apresenta 2 a 3 perguntas focadas relevantes para o tipo de pesquisa
    • Detecta se a pesquisa é técnica ou geral com base em palavras-chave
    • Permite que os usuários selecionem opções predefinidas (1-4) ou forneçam texto personalizado
    • Perguntas cobrem: Escopo/Período de tempo, Nível de profundidade, Áreas de foco
  3. Aprimora o prompt: Combina o prompt original com as respostas do usuário em parâmetros de pesquisa estruturados

  4. Salva o arquivo de prompt: Escreve o prompt aprimorado em research_prompt_YYYYMMDD_HHMMSS.txt para reprodutibilidade

  5. Executa a pesquisa profunda: Executa o script principal deep_research.py com:

    • Modelo: o4-mini-deep-research (configurável via --model)
    • Timeout: 1800 segundos / 30 minutos (configurável via --timeout)
    • Ferramentas: Busca na web habilitada por padrão

Etapa 4: Apresentar Resultados ao Usuário

O script automaticamente:

  • Salva arquivo markdown: Relatório de pesquisa com fontes salvo em research_report_YYYYMMDD_HHMMSS.md
  • Imprime no terminal: Relatório de pesquisa completo com formatação markdown
  • Lista fontes da web: URLs numeradas referenciadas na pesquisa
  • Confirma a conclusão: Caminho onde os arquivos de pesquisa foram salvos

Nota de Eficiência de Tokens: A pesquisa profunda leva de 10 a 20 minutos. O script é executado de forma síncrona (bloqueante) sem polling intermediário, minimizando o uso de tokens durante a espera.

Recursos Inclusos

Scripts

scripts/run_deep_research.py (Ponto de Entrada Principal)

O script de orquestração que lida com:

  • Avaliação da qualidade do prompt
  • Perguntas interativas de aprimoramento (com detecção inteligente para pesquisa técnica vs. geral)
  • Salvamento e timestamp do prompt
  • Execução da pesquisa profunda principal

Principais Recursos:

  • Aprimoramento inteligente: Só faz perguntas se o prompt for breve/genérico
  • Perguntas baseadas em modelo: Conjuntos de perguntas diferentes para pesquisa técnica vs. geral
  • Entrada flexível: Opções numeradas + entrada de texto personalizado
  • Tratamento de erros: Mensagens úteis se deep_research.py não for encontrado

Opções disponíveis:

python3 run_deep_research.py <prompt> [OPÇÕES]
  --no-enhance              Pular perguntas de aprimoramento
  --model <model>           Modelo a ser usado (padrão: o4-mini-deep-research)
  --timeout <segundos>      Timeout em segundos (padrão: 1800)
  --output-dir <caminho>    Onde salvar o arquivo de prompt

assets/deep_research.py

Script principal que faz interface com a API de Pesquisa Profunda da OpenAI. Lida com:

  • Autenticação da API via OPENAI_API_KEY
  • Criação e execução de solicitações
  • Salvamento automático em markdown: Salva arquivos de relatório com timestamp por padrão
  • Formatação de saída (relatório + fontes com metadados)
  • Tratamento de erros e tentativas

Novas opções de linha de comando:

--output-file <caminho>      Caminho personalizado para arquivo de saída
--no-save                    Desativar salvamento automático em markdown

Referências

references/workflow.md

Documentação detalhada do fluxo de trabalho cobrindo:

  • Fluxo de trabalho completo da habilidade com exemplos
  • Estratégias de aprimoramento de prompt
  • Explicação dos parâmetros de pesquisa
  • Guia de integração para Claude
  • Referência da interface de linha de comando
  • Tratamento de erros e solução de problemas
  • Dicas para pesquisa eficaz

Comportamentos Chave

Aprimoramento Inteligente de Prompt

A habilidade determina de forma inteligente se o aprimoramento é necessário:

  • Ativa aprimoramento para prompts com < 15 palavras ou início genérico
  • Pula aprimoramento para prompts detalhados e específicos
  • Permite que usuários desativem com a flag --no-enhance
  • Consciente de modelo: Usa perguntas diferentes para pesquisa técnica vs. geral

Parâmetros de Pesquisa

Prompts aprimorados incluem:

  • Consulta original do usuário com contexto completo
  • Preferências de escopo e período de tempo
  • Nível de profundidade desejado (resumo, técnico, implementação, comparativo)
  • Áreas de foco específicas (desempenho, custo, segurança, etc.)

Esses parâmetros ajudam o modelo de pesquisa profunda a entregar resultados mais direcionados e relevantes.

Reprodutibilidade

Cada execução de pesquisa:

  • Salva o prompt exato usado em um arquivo com timestamp
  • Permite rastrear decisões de pesquisa
  • Permite pesquisas de acompanhamento usando os mesmos prompts ou modificados
  • Mantém trilha de auditoria dos parâmetros de pesquisa

Exemplos

Prompt Breve com Aprimoramento

Usuário: "Pesquise as soluções RAG de código aberto mais eficazes"

Comportamento do script:

  1. Detecta prompt breve (12 palavras) + palavras-chave técnicas ("código aberto", "RAG")
  2. Faz perguntas de pesquisa técnica:
    • Escopo de tecnologia: Apenas código aberto? (Usuário: Sim)
    • Métricas chave: Desempenho/benchmarks? (Usuário: Velocidade e Precisão)
    • Casos de uso: Implantação em produção? (Usuário: Vários aspectos)
  3. Aprimora para um prompt detalhado com parâmetros
  4. Salva e executa pesquisa profunda
  5. Retorna relatório abrangente com benchmarks comparativos e URLs de fontes

Prompt Detalhado Sem Aprimoramento

Usuário: "Analise o impacto dos grandes modelos de linguagem na produtividade de desenvolvedores de software em 2024-2025, focando em ferramentas de geração de código, programação em par e métricas de produtividade."

Comportamento do script:

  1. Detecta prompt detalhado (24 palavras) com escopo/foco específico
  2. Pula perguntas de aprimoramento
  3. Salva e executa pesquisa profunda imediatamente
  4. Retorna análise focada alinhada com as especificações do usuário

Requisitos

  • Python 3.7+
  • Chave de API OpenAI (definida via variável de ambiente OPENAI_API_KEY ou arquivo .env)
  • Conexão com a internet (para busca na web)
  • 30+ minutos para conclusão da pesquisa (timeout configurável)

Fluxo de Trabalho Eficiente em Tokens

Otimização de Tarefas de Longa Execução

Consultas de pesquisa profunda normalmente levam de 10 a 20 minutos para serem concluídas. Esta habilidade é otimizada para minimizar o uso de tokens durante longas esperas:

Como funciona:

  1. Execução síncrona: O script é executado como um subprocesso bloqueante (sem polling em segundo plano)
  2. Sem verificações intermediárias: Claude espera silenciosamente pela conclusão sem atualizações de status
  3. Saída única: Os resultados são apresentados uma vez no final
  4. Salvamento automático: Arquivos Markdown são salvos automaticamente, sem necessidade de intervenção manual

Economia de tokens:

  • Abordagem tradicional: Verificar status a cada 30 segundos = ~40 verificações × 500 tokens = ~20.000 tokens desperdiçados
  • Esta abordagem: Espera única = ~1.000 tokens no total

Gerenciamento Automático de Arquivos

A habilidade gera e salva arquivos automaticamente:

Arquivos gerados:

  • research_prompt_YYYYMMDD_HHMMSS.txt - Prompt de pesquisa aprimorado com parâmetros
  • research_report_YYYYMMDD_HHMMSS.md - Relatório markdown completo com:
    • Seções de pesquisa (histórica, cognitiva, cultural, etc.)
    • Citações de fontes numeradas
    • Rodapé de metadados (data, modelo)

Opções de personalização:

# Local de saída personalizado
python3 deep_research.py --prompt-file prompt.txt --output-file my_research.md

# Desativar salvamento automático (apenas saída no terminal)
python3 deep_research.py --prompt-file prompt.txt --no-save

Solução de Problemas

OPENAI_API_KEY Ausente

Erro: "Missing OPENAI_API_KEY"

Solução:

  • Defina a variável de ambiente: export OPENAI_API_KEY="sua-chave"
  • Ou crie um arquivo .env no diretório de trabalho com OPENAI_API_KEY=sua-chave

deep_research.py Não Encontrado

Erro: "Could not find deep_research.py"

Solução:

  • Certifique-se de que a habilidade está instalada corretamente com os assets
  • O script pesquisa em: pasta de assets da habilidade → diretório atual → diretório pai

Timeout da Pesquisa

Erro: Solicitação expira após 30 minutos

Solução:

  • Aumente o timeout: --timeout 5400 (90 minutos)
  • Simplifique o prompt para reduzir o escopo da pesquisa
  • Execute durante horários de menor movimento para respostas potencialmente mais rápidas da API

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

Build content-focused websites with Astro — zero JS by default, islands architecture, multi-framework components, and Markdown/MDX support.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Next.js App Router principles. Server Components, data fetching, routing patterns.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

Habilidades Relacionadas