Esta es una serie de 10 partes que comparte 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. Lee en orden o salta a cualquier publicación que te interese:
| 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 (HABILIDAD) 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, cuándo leer de nuevo.
La CLI por sí sola no es suficiente
Los comandos de la CLI otorgan a un Agente poder de ejecución.
Pero el poder sin juicio lleva a problemas:
| Poder de la CLI | Riesgo sin juicio |
|---|---|
| Crear caso de prueba | Crea en un proyecto incorrecto |
| Actualizar escenario de prueba | Actualiza sin leer de nuevo |
| Importar pasos | Importa sin verificar la estructura existente |
| Ejecutar pruebas | Ejecuta sin validar cambios |
Los Agentes necesitan más que comandos. Necesitan juicio operativo.
¿Qué es SKILL?
Una SKILL es una **guía operativa escrita para Agentes de IA**.
No es:
- Una lista de comandos simple
- Un manual de referencia
- Una página de ayuda
Es:
| Contenido de SKILL | Propósito |
|---|---|
| Cuándo usar un comando | Tipo de tarea → mapeo de comandos |
| Qué comando va primero | Guía de secuencia |
| Qué campos no deben adivinarse | Límites de seguridad |
| Cuándo validar | Colocación de la puerta de calidad |
| Cuándo leer de nuevo | Momento de verificación |
| Cuándo ejecutar pruebas | Flujo de trabajo de confirmación |
SKILL otorga juicio operativo a los Agentes.
Instalación
SKILL es un complemento de Apidog CLI:
# Instala SKILL para tu Agente de IA
apidog skill installEsto instala **8 SKILLS complementarias** que ayudan a los Agentes a comprender:
- Semántica de comandos de la CLI
- Estructuras de recursos
- Flujos de trabajo de tareas
- Manejo de errores
- Patrones de verificación
Por qué SKILL Importa: Flujos de Trabajo Ocultos
El Agente aún necesita saber cómo las tareas deben descomponerse en flujos de ejecución transversales del negocio.
Esta experiencia no puede ser:
- Escrita de forma exhaustiva en las descripciones de las herramientas (consumiría demasiado contexto)
- Dispersa en el contexto del chat (se perdería entre sesiones)
- Memorizada por el modelo (específica del producto, no conocimiento general)
Los flujos de trabajo ocultos y los "escollos del negocio" requieren una guía explícita.
Ejemplo: Mantenimiento de Escenarios de Prueba
Considera mantener un escenario de prueba complejo.
Enfoque incorrecto (el Agente escribe a mano desde cero):
Agente: "Crearé la estructura del escenario de prueba manualmente"
Agente: Escribe un array completo de pasos con aserciones, extractores, procesadores
Resultado: Errores de campo, comparadores incorrectos, campos obligatorios faltantes
CLI: Rechaza la escritura o crea un escenario incompletoEnfoque correcto (codificado en SKILL):
| Paso | Por qué |
|---|---|
| 1. Importar pasos existentes de endpoints o casos de prueba | No escribir estructuras complejas a mano |
| 2. Leer de nuevo la estructura completa | Ver el formato importado real |
| 3. Realizar modificaciones locales | Trabajar con una base precisa |
| 4. Validar antes de actualizar | Detectar errores localmente |
| 5. Ejecutar escenario | Verificar comportamiento |
SKILL no solo dice "hay un comando `test-scenario update`".
Dice:
"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."
Los Comandos Detrás de la Guía de SKILL
Aquí están los comandos reales que SKILL guía a los Agentes a usar:
# Paso 1: Importar pasos de endpoints
apidog test-scenario import-steps <scenarioId> --project <projectId> \
--source endpoint --ids <endpointIds> --sync manual
# Paso 2: Leer de nuevo con todo detalle
apidog test-scenario get <scenarioId> --project <projectId> \
--with-case-detail
# Paso 3: Actualizar partes específicas (el Agente genera JSON de actualización)
# Paso 4: Validar antes de actualizar
apidog cli-schema validate test-scenario-update --file ./scenario-update.json
# Paso 5: Ejecutar actualización
apidog test-scenario update <scenarioId> --project <projectId> \
--file ./scenario-update.json
# Paso 6: Ejecutar verificación
apidog run --project <projectId> --test-scenario <scenarioId>SKILL le dice al Agente **cuándo usar cada comando** y **por qué**.
Conocimiento Clave: get--with-case-detail
SKILL enfatiza:
"Usa get--with-case-detail para obtener la estructura real, no para imaginar el caso dentro de los pasos."Por qué esto importa:
Sin get--with-case-detail |
Con get--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 aserción/extractor |
| El Agente adivina los nombres de los 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 evolucionable y versionable.**
Por qué esto importa
| Desafío | Solución SKILL |
|---|---|
| Los comandos de la CLI cambian | SKILL puede actualizarse para coincidir |
| Los usuarios tienen flujos de trabajo personalizados | SKILL puede personalizarse |
| Nuevas características del producto | SKILL puede extenderse |
| Mejoras en el flujo de trabajo | SKILL puede refinarse |
Cómo funciona
A los Agentes se les otorgan **permisos de escritura** para SKILL.
Si SKILL se queda atrás o se vuelve difícil de usar:
- El Agente puede modificarlo
- El Agente puede sugerir mejoras
- SKILL evoluciona a través del uso
SKILL no es documentación congelada. Es código operativo vivo.
La Capa de Compatibilidad
Aprendimos esto de errores reales:
Problema descubierto:
Algunos pasos del escenario, durante las 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 un manejo especial
- Los Agentes no conocían estos marcadores
- La semántica del producto requería flags específicos
Solución:
- Lógica de compatibilidad incorporada en la CLI
- La CLI maneja los marcadores internos automáticamente
- Los usuarios y Agentes no necesitan conocer los detalles internos
El significado de la restricción está estratificado en SKILL:
SKILL le dice al Agente que use los comandos correctos. La CLI maneja la semántica del producto detrás de esos comandos. El Agente no necesita 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 totalmente expuesta al modelo.
| Alternativa | Problema |
|---|---|
| Cargar todo SKILL en el contexto | Carga de tokens |
Poner todas las reglas en --help |
Compiten por la atención |
| Escribir en el prompt | No se puede actualizar |
Enfoque de SKILL:
- El Agente carga SKILL **bajo demanda**
- SKILL se carga cuando se identifica el tipo de tarea
- Solo la guía de flujo de trabajo relevante entra en el contexto
SKILL vs. Documentación
| Documentación | SKILL |
|---|---|
| Para que los humanos lean | Para que los 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 |
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, importar, actualizar |
| 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 campo
- Puntos de control de validación
- Patrones de verificación
Qué sigue
Ahora que hemos establecido los 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 una 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 modificarlo
- La CLI absorbe la semántica del producto, SKILL guía el flujo de trabajo
- La carga bajo demanda previene la carga de 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.