Esta serie de 10 partes explica cómo Apidog desarrolló Apidog CLI, una herramienta de línea de comandos para pruebas de API y gestión del ciclo de vida de las API. Puedes leerla en orden o saltar directamente a la parte que necesites.
| # | Título | Enfoque |
|---|---|---|
| 1 | Construimos 126 Herramientas MCP. Pero no es la Mejor Solución para el Agente | Descubrimiento del problema |
| 2 | Por qué Desarrollamos el Nuevo Apidog CLI | Desarrollo de la arquitectura |
| 3 | La Regla de Oro: La CLI Produce Hechos, el Modelo Actúa sobre Hechos | Filosofía central |
| 4 | agentHints: Enseñando a las CLIs a Hablar con los Agentes |
Salida estructurada |
| 5 | SKILL: Enviando Experiencia Operacional como Código | Experiencia operacional |
| 6 | Los Números no Mienten: 30% Menos de Llamadas a Herramientas, 25% Menos de Tokens | Resultados cuantitativos |
| 7 | Del PRD al Bucle de Pruebas: Un Flujo de Trabajo Completo del Agente con Apidog CLI | Tutorial práctico |
| 8 | Por qué la Compatibilidad con CI/CD no es Negociable para las Herramientas de Agente | Perspectiva DevOps |
| 9 | Rama de IA: Cambios de Proyecto más Seguros con Agentes de IA | Capa de seguridad |
| 10 | "Spec-First" fue Ayer. Bienvenido a "Skill-First". | Visión y futuro |
Una SKILL no es solo una referencia de comandos. Es una guía operativa para Agentes de IA: cuándo usar un comando, cuál va primero, qué campos no deben ser adivinados, cuándo validar y cuándo leer de nuevo.
La CLI por sí sola no es suficiente
Los comandos de una CLI dan a un Agente poder de ejecución. Pero ejecutar comandos no significa tomar buenas decisiones.
| Poder de la CLI | Riesgo sin juicio operativo |
|---|---|
| Crear un caso de prueba | Lo crea en el proyecto incorrecto |
| Actualizar un escenario de prueba | Actualiza sin leer la estructura actual |
| Importar pasos | Importa sin verificar la estructura existente |
| Ejecutar pruebas | Ejecuta sin validar los cambios |
Un Agente necesita más que comandos. Necesita saber qué hacer primero, qué no debe adivinar y cuándo validar.
¿Qué es SKILL?
Una SKILL es una guía operativa escrita para Agentes de IA.
No es:
- Una lista simple de comandos
- Un manual de referencia
- Una página de ayuda
Es una capa de instrucciones ejecutables para decidir cómo trabajar con la CLI.
| Contenido de SKILL | Propósito |
|---|---|
| Cuándo usar un comando | Mapear tipo de tarea → comando |
| Qué comando va primero | Definir la secuencia correcta |
| Qué campos no deben adivinarse | Establecer límites de seguridad |
| Cuándo validar | Insertar puertas de calidad |
| Cuándo leer de nuevo | Verificar el estado real |
| Cuándo ejecutar pruebas | Confirmar comportamiento |
SKILL otorga juicio operativo a los Agentes.
Instalación
SKILL se instala como complemento de Apidog CLI:
# Instala SKILL para tu Agente de IA
apidog skill install
Después de instalarlo, el Agente puede usar las SKILLS para entender:
- Semántica de comandos de la CLI
- Estructuras de recursos
- Flujos de trabajo por tipo de tarea
- Manejo de errores
- Patrones de verificación
Por qué SKILL importa: flujos de trabajo ocultos
Muchas tareas no son una llamada directa a un comando. Requieren pasos intermedios y reglas de negocio.
Esta experiencia no debería estar:
- Escrita exhaustivamente en descripciones de herramientas, porque consumiría demasiado contexto
- Dispersa en el historial del chat, porque se perdería entre sesiones
- Memorizada por el modelo, porque es conocimiento específico del producto
Los flujos de trabajo ocultos y los escollos del negocio requieren una guía explícita.
Ejemplo práctico: mantenimiento de escenarios de prueba
Supongamos que un Agente debe mantener un escenario de prueba complejo.
Enfoque incorrecto
El Agente intenta escribir toda la estructura desde cero:
Agente: "Crearé la estructura del escenario de prueba manualmente"
Agente:
- Escribe un array completo de pasos
- Añade aserciones
- Añade extractores
- Añade procesadores
Resultado:
- Errores de campo
- Comparadores incorrectos
- Campos obligatorios faltantes
CLI:
- Rechaza la escritura
- O crea un escenario incompleto
El problema no es que el Agente no pueda generar JSON. El problema es que está generando una estructura compleja sin partir de una fuente real.
Enfoque correcto codificado en SKILL
| Paso | Por qué |
|---|---|
| 1. Importar pasos existentes desde endpoints o casos de prueba | Evita escribir estructuras complejas a mano |
| 2. Leer de nuevo la estructura completa | Permite ver el formato real importado |
| 3. Hacer modificaciones locales | Trabaja sobre una base precisa |
| 4. Validar antes de actualizar | Detecta errores antes de escribir |
| 5. Ejecutar el escenario | Verifica el comportamiento |
SKILL no solo dice que existe un comando como test-scenario update.
También indica la ruta segura:
Los escenarios complejos no son adecuados para escribir estructuras completas a mano desde cero. Una ruta más estable es primero importar los pasos existentes de endpoints o casos, luego leer de nuevo la estructura completa y finalmente realizar modificaciones locales.
Flujo recomendado con comandos
Este es el flujo que SKILL guía al Agente a seguir.
1. Importar pasos desde endpoints
apidog test-scenario import-steps <scenarioId> --project <projectId> \
--source endpoint --ids <endpointIds> --sync manual
2. Leer de nuevo el escenario con detalle completo
apidog test-scenario get <scenarioId> --project <projectId> \
--with-case-detail
3. Preparar el archivo de actualización
El Agente genera un archivo local con los cambios:
./scenario-update.json
La idea es modificar solo las partes necesarias, no reconstruir toda la estructura desde cero.
4. Validar antes de actualizar
apidog cli-schema validate test-scenario-update --file ./scenario-update.json
5. Aplicar la actualización
apidog test-scenario update <scenarioId> --project <projectId> \
--file ./scenario-update.json
6. Ejecutar la verificación
apidog run --project <projectId> --test-scenario <scenarioId>
SKILL le indica al Agente cuándo usar cada comando y por qué ese orden reduce errores.
Conocimiento clave: --with-case-detail
SKILL enfatiza esta regla:
Usa
--with-case-detailpara obtener la estructura real, no para imaginar el caso dentro de los pasos.
Por qué importa:
Sin --with-case-detail
|
Con --with-case-detail
|
|---|---|
| Los pasos muestran solo IDs | Los pasos muestran estructuras de caso completas |
| El Agente no conoce el formato interno | El Agente ve el formato real de aserciones y extractores |
| El Agente adivina nombres de campos | El Agente trabaja con ejemplos reales |
Obtener la estructura real evita actualizaciones basadas en la imaginación.
Evolucionabilidad: SKILL puede cambiar
Apidog SKILL es una experiencia operativa versionable y evolucionable.
| Desafío | Solución con SKILL |
|---|---|
| Los comandos de la CLI cambian | SKILL puede actualizarse |
| Los usuarios tienen flujos personalizados | SKILL puede personalizarse |
| Aparecen nuevas características | SKILL puede extenderse |
| Se detectan mejores patrones | SKILL puede refinarse |
Cómo funciona
A los Agentes se les pueden otorgar permisos de escritura sobre SKILL.
Si una SKILL queda desactualizada o resulta difícil de usar:
- El Agente puede modificarla
- El Agente puede sugerir mejoras
- La guía evoluciona con el uso real
SKILL no es documentación congelada. Es código operativo vivo.
La capa de compatibilidad
Este patrón surgió a partir de errores reales.
Problema descubierto
Algunos pasos del escenario, durante actualizaciones secundarias, tenían los pasos externos actualizados correctamente, pero los casos HTTP internos no se actualizaban correctamente.
Causa raíz
- Los marcadores internos de actualización de casos necesitaban manejo especial
- Los Agentes no conocían esos marcadores
- La semántica del producto requería flags específicos
Solución
- Incorporar lógica de compatibilidad en la CLI
- Hacer que la CLI maneje automáticamente los marcadores internos
- Evitar que usuarios y Agentes tengan que conocer detalles internos
El diseño queda estratificado:
- SKILL guía al Agente para usar el flujo correcto
- CLI encapsula la semántica del producto
- Agente ejecuta sin tener que entender los marcadores internos
Carga bajo demanda
SKILL sigue el mismo principio que cli-schema:
La complejidad debe ser absorbida por la ejecución y la documentación, no exponerse por completo al modelo.
| Alternativa | Problema |
|---|---|
| Cargar toda la SKILL en el contexto | Aumenta el consumo de tokens |
Poner todas las reglas en --help
|
Compiten por la atención |
| Escribir las reglas en el prompt | No se actualizan fácilmente |
El enfoque de SKILL:
- El Agente carga SKILL bajo demanda
- La SKILL se carga cuando se identifica el tipo de tarea
- Solo entra al contexto la guía relevante para el flujo actual
Esto reduce ruido y mantiene el contexto enfocado en la tarea.
SKILL vs. documentación
| Documentación | SKILL |
|---|---|
| Para que humanos lean | Para que Agentes ejecuten |
| Explica qué hacen los comandos | Explica cuándo usarlos |
| Referencia estática | Flujo de trabajo dinámico |
| Exhaustiva | Centrada en la tarea |
| Externa al Agente | Integrada con el Agente |
La documentación sigue siendo útil. SKILL añade una capa adicional: instrucciones operativas para que un Agente tome mejores decisiones durante la ejecución.
Las 8 SKILLS complementarias
Apidog proporciona 8 SKILLS complementarias:
| SKILL | Cobertura |
|---|---|
| Gestión de proyectos | Proyectos, metadatos, recursos |
| Diseño de API | Endpoints, esquemas, definiciones |
| Gestión de entornos | Entornos, variables |
| Creación de casos de prueba | Pruebas de un solo endpoint, aserciones |
| Gestión de escenarios de prueba | Pruebas de múltiples pasos, importación, actualización |
| Organización de suites de prueba | Agrupación, ejecución |
| Flujos de trabajo de importación/exportación | Migración de datos, respaldo |
| Integración CI/CD | Comandos de pipeline, informes |
Cada SKILL contiene:
- Identificación del tipo de tarea
- Guía de secuencia de comandos
- Límites de seguridad de campos
- Puntos de control de validación
- Patrones de verificación
Qué sigue
Hasta aquí tenemos tres componentes centrales:
-
cli-schema validate: puerta de calidad -
agentHints: navegación al siguiente paso - SKILL: juicio de flujo de trabajo
La siguiente pregunta es:
¿Esto realmente funciona? ¿Cuáles son los números?
En la Parte 6, Los números no mienten: 30% menos de llamadas a herramientas, 25% menos de tokens, compartiremos los resultados cuantitativos de nuestras comparaciones internas y explicaremos de dónde provienen los ahorros.
Puntos clave
- La CLI otorga poder de ejecución; SKILL otorga juicio operativo.
- SKILL es una guía operativa, no una referencia de comandos.
- Los flujos de trabajo ocultos requieren guía explícita.
- Importar pasos → leer de nuevo → actualizar localmente es más seguro que escribir a mano.
-
--with-case-detailevita actualizaciones basadas en la imaginación. - SKILL es evolucionable: los Agentes pueden modificarla.
- La CLI absorbe la semántica del producto; SKILL guía el flujo de trabajo.
- La carga bajo demanda evita sobrecargar el contexto.
Descarga Apidog para diseñar, simular, probar y documentar APIs en un solo espacio de trabajo. Obtén más información sobre Apidog CLI para pruebas de API de línea de comandos, automatización de CI y flujos de trabajo de Agentes de IA.
Top comments (0)