Habilidad de Investigación Profunda
Propósito
Esta habilidad permite realizar investigaciones exhaustivas y habilitadas para internet sobre cualquier tema utilizando la API de OpenAI Deep Research (modelo o4-mini-deep-research). Mejora de forma inteligente las consultas de investigación del usuario a través de preguntas interactivas de aclaración, asegura que los parámetros de investigación se guarden para su reproducibilidad y ejecuta investigación profunda con capacidades completas de búsqueda web.
Cuándo Usar Esta Habilidad
Activa esta habilidad cuando:
- El usuario solicite investigación sobre un tema específico
- El usuario pida análisis, investigación o recopilación completa de información
- El usuario quiera explorar un tema con búsqueda web y razonamiento
- El usuario proporcione una consulta de investigación breve que podría refinarse
- El usuario quiera comprender el estado actual, tendencias o comparaciones en un campo
Ejemplos de solicitudes de usuario:
- "Investiga las soluciones RAG de código abierto más efectivas con alto rendimiento en benchmarks"
- "¿Cuáles son los últimos desarrollos de IA en 2025?"
- "Necesito un análisis completo de los sistemas de bases de datos distribuidas"
- "Encuentra las mejores prácticas para implementar búsqueda vectorial"
- "Investiga cómo la IA está impactando la industria de la ingeniería de software"
Resumen del Flujo de Trabajo
Entrada del Usuario
↓
Evaluación: ¿Es la consulta demasiado breve?
↓
SÍ → Hacer Preguntas de Mejora → Recopilar Respuestas
↓ ↓
└───────→ Construir Consulta Mejorada ←──┘
↓
Guardar en Archivo con Marca de Tiempo
↓
Ejecutar deep_research.py
↓
Informe de Salida + Fuentes
↓
Presentar al Usuario
Cómo Debe Usar Claude Esta Habilidad
Importante para la Eficiencia de Tokens: La investigación profunda toma de 10 a 20 minutos en completarse. La habilidad está diseñada para ejecutarse de forma síncrona (bloqueante) sin verificaciones de estado intermedias. Este enfoque minimiza el uso de tokens durante la espera. Claude debe:
- Iniciar la investigación
- Esperar a que se complete (el subproceso se bloquea automáticamente)
- Presentar los resultados finales una vez completados
No es necesario realizar sondeos periódicos ni actualizaciones de estado durante la ejecución.
Paso 1: Aceptar la Solicitud de Investigación
Recibe la consulta de investigación del usuario. Esta puede variar desde breve ("Últimas tendencias de IA") hasta muy detallada ("Impacto de los modelos de lenguaje en la productividad de los desarrolladores con enfoque en 2024-2025").
Paso 2: Ejecutar el Script de Orquestación
Ejecuta el script de orquestación principal de la habilidad con la consulta de investigación del usuario:
python3 scripts/run_deep_research.py "Tu consulta de investigación aquí"
El script se encuentra en scripts/run_deep_research.py dentro de la instalación de la habilidad.
Paso 3: Flujo de Ejecución del Script
El script automáticamente:
-
Evalúa la completitud de la consulta: Comprueba si la consulta es demasiado breve o genérica (< 15 palabras o comienza con "qué es", "cómo", etc.)
-
Hace preguntas de aclaración (si es necesario):
- Presenta 2-3 preguntas enfocadas relevantes al tipo de investigación
- Detecta si la investigación es técnica o general basándose en palabras clave
- Permite a los usuarios seleccionar entre opciones predefinidas (1-4) o proporcionar texto personalizado
- Las preguntas cubren: Alcance/Período de tiempo, Nivel de profundidad, Áreas de enfoque
-
Mejora la consulta: Combina la consulta original con las respuestas del usuario en parámetros de investigación estructurados
-
Guarda el archivo de consulta: Escribe la consulta mejorada en
research_prompt_YYYYMMDD_HHMMSS.txtpara reproducibilidad -
Ejecuta la investigación profunda: Ejecuta el script central
deep_research.pycon:- Modelo: o4-mini-deep-research (configurable mediante
--model) - Tiempo de espera: 1800 segundos / 30 minutos (configurable mediante
--timeout) - Herramientas: Búsqueda web habilitada por defecto
- Modelo: o4-mini-deep-research (configurable mediante
Paso 4: Presentar los Resultados al Usuario
El script automáticamente:
- Guarda el archivo markdown: Informe de investigación con fuentes guardado en
research_report_YYYYMMDD_HHMMSS.md - Imprime en la terminal: Informe de investigación completo con formato markdown
- Lista las fuentes web: URLs numeradas referenciadas en la investigación
- Confirma la finalización: Ruta donde se guardaron los archivos de investigación
Nota sobre eficiencia de tokens: La investigación profunda toma de 10 a 20 minutos. El script se ejecuta de forma síncrona (bloqueante) sin sondeo intermedio, minimizando el uso de tokens durante la espera.
Recursos Incluidos
Scripts
scripts/run_deep_research.py (Punto de Entrada Principal)
El script de orquestación que maneja:
- Evaluación de la calidad de la consulta
- Preguntas interactivas de mejora (con detección inteligente para investigación técnica vs. general)
- Guardado y marcado de tiempo de la consulta
- Ejecución de la investigación profunda central
Características Clave:
- Mejora inteligente: Solo hace preguntas si la consulta es breve o genérica
- Preguntas basadas en plantillas: Diferentes conjuntos de preguntas para investigación técnica vs. general
- Entrada flexible: Opciones numeradas + entrada de texto personalizado
- Manejo de errores: Mensajes útiles si no se encuentra deep_research.py
Opciones disponibles:
python3 run_deep_research.py <consulta> [OPCIONES]
--no-enhance Omitir preguntas de mejora
--model <modelo> Modelo a utilizar (por defecto: o4-mini-deep-research)
--timeout <segundos> Tiempo de espera en segundos (por defecto: 1800)
--output-dir <ruta> Dónde guardar el archivo de consulta
assets/deep_research.py
Script central que interactúa con la API de OpenAI Deep Research. Maneja:
- Autenticación de API mediante OPENAI_API_KEY
- Creación y ejecución de solicitudes
- Guardado automático en markdown: Guarda archivos de informe con marca de tiempo por defecto
- Formato de salida (informe + fuentes con metadatos)
- Manejo de errores y reintentos
Nuevas opciones de línea de comandos:
--output-file <ruta> Ruta de archivo de salida personalizada
--no-save Deshabilitar el guardado automático en markdown
Referencias
references/workflow.md
Documentación detallada del flujo de trabajo que cubre:
- Flujo de trabajo completo de la habilidad con ejemplos
- Estrategias de mejora de consultas
- Explicación de los parámetros de investigación
- Guía de integración para Claude
- Referencia de la interfaz de línea de comandos
- Manejo de errores y solución de problemas
- Consejos para una investigación efectiva
Comportamientos Clave
Mejora Inteligente de Consultas
La habilidad determina de forma inteligente si se necesita mejora:
- Activa la mejora para consultas con < 15 palabras o comienzos genéricos
- Omite la mejora para consultas detalladas y específicas
- Permite a los usuarios deshabilitarla con la bandera
--no-enhance - Consciente de plantillas: Utiliza diferentes preguntas para investigación técnica vs. general
Parámetros de Investigación
Las consultas mejoradas incluyen:
- Consulta original del usuario con contexto completo
- Preferencias de alcance y período de tiempo
- Nivel de profundidad deseado (resumen, técnico, implementación, comparativo)
- Áreas de enfoque específicas (rendimiento, costo, seguridad, etc.)
Estos parámetros ayudan al modelo de investigación profunda a entregar resultados más específicos y relevantes.
Reproducibilidad
Cada ejecución de investigación:
- Guarda la consulta exacta utilizada en un archivo con marca de tiempo
- Permite rastrear las decisiones de investigación
- Permite investigaciones de seguimiento utilizando las mismas consultas o modificadas
- Mantiene un registro de auditoría de los parámetros de investigación
Ejemplos
Consulta Breve con Mejora
Usuario: "Investiga las soluciones RAG de código abierto más efectivas"
Comportamiento del script:
- Detecta consulta breve (12 palabras) + palabras clave técnicas ("código abierto", "RAG")
- Hace preguntas de investigación técnica:
- Alcance tecnológico: ¿Solo código abierto? (Usuario: Sí)
- Métricas clave: ¿Rendimiento/benchmarks? (Usuario: Velocidad y Precisión)
- Casos de uso: ¿Despliegue en producción? (Usuario: Múltiples aspectos)
- Mejora a una consulta detallada con parámetros
- Guarda y ejecuta la investigación profunda
- Devuelve un informe completo con benchmarks comparativos y URLs de fuentes
Consulta Detallada Sin Mejora
Usuario: "Analiza el impacto de los grandes modelos de lenguaje en la productividad de los desarrolladores de software en 2024-2025, centrándote en herramientas de generación de código, programación en pareja y métricas de productividad."
Comportamiento del script:
- Detecta consulta detallada (24 palabras) con alcance/enfoque específico
- Omite las preguntas de mejora
- Guarda y ejecuta la investigación profunda inmediatamente
- Devuelve un análisis enfocado alineado con las especificaciones del usuario
Requisitos
- Python 3.7+
- Clave de API de OpenAI (configurada mediante la variable de entorno
OPENAI_API_KEYo archivo.env) - Conexión a Internet (para búsqueda web)
- 30+ minutos para la finalización de la investigación (tiempo de espera configurable)
Flujo de Trabajo Eficiente en Tokens
Optimización de Tareas de Larga Duración
Las consultas de investigación profunda suelen tomar 10-20 minutos en completarse. Esta habilidad está optimizada para minimizar el uso de tokens durante largas esperas:
Cómo funciona:
- Ejecución síncrona: El script se ejecuta como un subproceso bloqueante (sin sondeo en segundo plano)
- Sin verificaciones intermedias: Claude espera en silencio hasta que se complete, sin actualizaciones de estado
- Salida única: Los resultados se presentan una vez al final
- Guardado automático: Los archivos markdown se guardan automáticamente, sin necesidad de intervención manual
Ahorro de tokens:
- Enfoque tradicional: Verificar el estado cada 30 segundos = ~40 verificaciones × 500 tokens = ~20,000 tokens desperdiciados
- Este enfoque: Una sola espera = ~1,000 tokens en total
Gestión Automática de Archivos
La habilidad genera y guarda archivos automáticamente:
Archivos generados:
research_prompt_YYYYMMDD_HHMMSS.txt- Consulta de investigación mejorada con parámetrosresearch_report_YYYYMMDD_HHMMSS.md- Informe markdown completo con:- Secciones de investigación (histórica, cognitiva, cultural, etc.)
- Citas de fuentes numeradas
- Pie de página de metadatos (fecha, modelo)
Opciones de personalización:
# Ubicación de salida personalizada
python3 deep_research.py --prompt-file prompt.txt --output-file my_research.md
# Deshabilitar el guardado automático (solo salida en terminal)
python3 deep_research.py --prompt-file prompt.txt --no-save
Solución de Problemas
OPENAI_API_KEY Faltante
Error: "Missing OPENAI_API_KEY"
Solución:
- Configurar la variable de entorno:
export OPENAI_API_KEY="tu-clave" - O crear un archivo
.enven el directorio de trabajo conOPENAI_API_KEY=tu-clave
deep_research.py No Encontrado
Error: "Could not find deep_research.py"
Solución:
- Asegurarse de que la habilidad esté instalada correctamente con los assets
- El script busca en: carpeta de assets de la habilidad → directorio actual → directorio padre
Tiempo de Espera de Investigación Agotado
Error: La solicitud se agota después de 30 minutos
Solución:
- Aumentar el tiempo de espera:
--timeout 5400(90 minutos) - Simplificar la consulta para reducir el alcance de la investigación
- Ejecutar durante horas de menor actividad para posibles respuestas más rápidas de la API