Communitygithub.com

aetox-skills/create-agent

Skill de diseño de agentes con enfoque en el alcance — define el alcance claramente antes de crear el agente.

¿Qué es create-agent?

Este skill te guía en el diseño de agentes de IA con una disciplina de 'alcance primero' (scope-first). Antes de escribir cualquier prompt, configuración o enlace de herramientas, debes pasar por una entrevista de alcance estructurada cuya profundidad depende de la complejidad del agente. No es un skill para redactar prompts, sino para validar el alcance; el resultado es un **Agent Spec** (especificación del agente) validado, un plano que otra IA o humano puede usar para construir el agente correctamente. El skill define 8 dimensiones esenciales (Arquetipo, Personalidad, Capacidades, E/S, Ecosistema, Memoria, Ciclo de Vida y Riesgo/Métricas) y proporciona reglas estrictas, como 'alcance antes de construir', 'profundidad mínima suficiente' y 'inferir primero, preguntar después'. Soporta 4 niveles de profundidad (Rápido, Estándar, Profundo, Crítico) y un sistema de arquetipos para adaptar la entrevista según el tipo de agente (Sistema, Creativo, Desarrollador, Escriba, Especialista, Orquestador, Investigador, Juego). Está diseñado para herramientas como Claude Code, Cursor y Codex, y garantiza que el agente se construya solo después de que el alcance sea aprobado explícitamente.

Compatible con✓Claude Code~Codex CLI~Cursor✓OpenCode
npx skills add aetox-skills/create-agent

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Crear Agente

Propósito

Diseña agentes de IA con una disciplina de alcance primero. Antes de escribir cualquier prompt, configuración o enlace de herramientas, debes pasar por una entrevista de alcance estructurada. La profundidad de la entrevista depende de la complejidad del agente que se está diseñando.

Este no es un skill para redactar prompts. Es un skill de validación de alcance. El resultado es un Agent Spec (Especificación del Agente) validado, un plano que otra IA o humano puede usar para construir el agente correctamente.

Cada especificación de agente define 8 dimensiones:

Arquetipo → Personalidad → Capacidades → E/S → Ecosistema → Memoria → Ciclo de Vida → Riesgo/Métricas

Reglas de Hierro

  1. Alcance antes de construir — Sin código, sin prompt, sin configuración de herramientas hasta que el alcance esté validado. Cero excepciones.

    Autoridad de Corrección: Se aplica únicamente a borradores/suposiciones de la especificación — corrige las suposiciones en la especificación que el usuario haya pasado por alto (dependencia faltante, contradicción, riesgo de seguridad) de inmediato, no preguntes antes, solo informa qué ajustaste y por qué. No modifiques archivos, configuraciones, herramientas o flujos de trabajo reales sin obtener aprobación. Solicita aprobación antes si la solución correcta requiere cambiar una herramienta nueva o un flujo de trabajo existente — pero si el sentido común permite corregir la especificación, hazlo directamente.

  2. Profundidad mínima suficiente — Por defecto, usa Rápido. Promueve a Estándar/Profundo/Crítico solo cuando aparezcan señales explícitas. No empieces en Estándar.

  3. Infiere primero, pregunta después — Antes de hacer una pregunta, intenta inferir la respuesta del contexto, el código base, los agentes existentes y lo que el usuario ya dijo. Solo pregunta sobre lo que sigue siendo genuinamente incierto.

  4. Primero el código base — Si la respuesta a una pregunta existe en configuraciones, documentación o agentes existentes, búscala. No preguntes. Excepción Greenfield: Si no existe un código base (sin index.md, AGENTS.md, opencode.jsonc o agentes existentes), omite el escaneo del código base y ve directamente a la entrevista.

  5. Minimiza los viajes de ida y vuelta — Infiere la especificación → presenta un borrador → deja que el usuario lo marque. Pregunta uno por uno solo para vacíos genuinos que el borrador no pueda resolver. Nunca sueltes 10 preguntas a la vez.

  6. Recomienda, no dejes abierto — Cada pregunta debe incluir una respuesta recomendada. Da algo para reaccionar.

  7. La especificación debe ser aprobada — Nunca construyas hasta que la Especificación del Agente esté explícitamente aprobada. Para el nivel Rápido, la confirmación del usuario del borrador inferido cuenta como aprobación. Documéntalo como Estado: Aprobado vía Rápido.

  8. Detente ante la señal — Cuando el usuario diga "suficiente" o "detente", detente. No discutas, no insistas por más.

  9. Genera una Especificación del Agente — Cada sesión produce una especificación validada, incluso en el nivel Rápido.


Sistema de Arquetipos de Agente

Los agentes siguen patrones basados en su arquetipo. Usa esta tabla para elegir el arquetipo correcto y comprender en qué dominios de la entrevista enfocarte u omitir.

Catálogo de Arquetipos

#ArquetipoPropósito PrincipalPersonalidad PredeterminadaHerramientas TípicasNivel Sugerido
🛠️SistemaAutomatizar, configurar, mantenerPráctico, conciso, directoCLI, sistema de archivos, Docker, gitRápido → Estándar
🎨CreativoDiseñar, visual, movimientoExpresivo, orientado a los detallesTailwind, GSAP, APIs de imágenesRápido → Estándar
💻DesarrolladorCódigo, arquitectura, depuraciónTécnico, preciso, minuciosoMCPs, linters, ejecutores de pruebasRápido → Profundo
📝EscribaDocumentar, escribir, organizarClaro, estructurado, pacienteObsidian, markdown, búsquedaRápido
🔬EspecialistaDominio único profundoAutoritario, meticulosoCLI/MCP específico del dominioRápido → Profundo
🎯OrquestadorCoordinar, delegar, gestionarSistemático, impulsado por procesosLista de agentes, protocolo de traspasoRápido → Crítico
🔍InvestigadorBuscar, analizar, sintetizarCurioso, analítico, minuciosoExa, Firecrawl, herramientas webRápido
🎮JuegoComportamiento específico del juegoJuguetón, adaptableAPI del juego, framework de botsRápido → Profundo

Lista de Minimización de Arquetipos

No es "saltar", sino indicar qué dominios deben ser breves o se pueden omitir si es obvio.

Hay 3 niveles:

  • Análisis profundo — Pregunta todo.
  • Breve — Solo 1-2 preguntas, luego resume.
  • Omitir si obvio — No preguntes si el sentido común lo puede determinar (ej. Escriba → Memoria = solo sesión).
ArquetipoBreveOmitir si obvioAnálisis profundo
SistemaIdentidad, E/SMemoriaCapacidades, Ecosistema
CreativoRiesgo/Métricas, Ciclo de VidaMemoriaIdentidad, E/S, Personalidad
DesarrolladorCiclo de VidaIdentidadCapacidades, Ecosistema, E/S
EscribaEcosistemaRiesgo/Métricas, MemoriaIdentidad, E/S
EspecialistaE/S, Ciclo de Vida—Capacidades, Riesgo/Métricas
Orquestador——Todos los dominios
InvestigadorCiclo de Vida, PersonalidadMemoriaCapacidades, E/S, Identidad
JuegoEcosistemaRiesgo/MétricasCapacidades, E/S, Personalidad

Desarrollador + Identidad: Breve, no omitir — la identidad (frontmatter) aún es necesaria porque determina cuándo se invoca al agente. Solo hazla breve (1-2 oraciones).

Selección de Arquetipo

Al entrevistar, recomienda un arquetipo basado en el propósito del agente. Si encajan múltiples arquetipos, elige el dominante y anota los secundarios.

Ejemplo: "Esto suena como un arquetipo Desarrollador con algo de superposición Especialista.
         Según la lista de minimización: Ciclo de Vida = breve, Identidad = breve (solo frontmatter),
         enfócate en el análisis profundo en Capacidades + Ecosistema."

Sistema de Niveles de Profundidad

No todos los agentes necesitan la misma profundidad. Este skill define 4 niveles. Por defecto, usa Rápido. Empieza ligero, escala solo cuando las señales lo demanden.

Nivel 1 — Rápido       (inferir → confirmar → construir, preguntar más si es incierto)
                        │                          ← POR DEFECTO
Nivel 2 — Estándar     (Presentar borrador → usuario marca → aprobar)
                        │
Nivel 3 — Profundo     (Estándar + Mapa de Ecosistema + Trazado de Dependencias)
                        │
Nivel 4 — Crítico      (Profundo + Modelo de Riesgo + Modelo de Costo + Compuertas de Seguridad)

Selección de Nivel

SeñalRápidoEstándarProfundoCrítico
Agente es nuevo o modificado (1-2 capacidades), alcance claro✅———
Agente existente, cambio pequeño✅———
Agente nuevo, propósito único, sin dependencias—✅——
Agente nuevo, 1-2 integraciones externas—✅✅—
Agente en ecosistema multi-agente——✅✅
Maneja pagos / autenticación / PII———✅
Se despliega a producción———✅
Alto costo de tokens por llamada———✅
Implicaciones de seguridad o cumplimiento———✅
Arquetipo = Orquestador———✅
Arquetipo = Especialista——✅—

Por defecto, usa Rápido. Promueve solo cuando haya señales explícitas presentes.

Regla de escalamiento: Si durante una entrevista de nivel inferior descubres señales que justifican un nivel superior, promueve explícitamente:

Nota de promoción:
  Disparador: [lo que encontraste]
  Evidencia: [dónde lo encontraste]
  Riesgo de quedarse: [por qué el nivel inferior es inseguro]

Nivel 1 — Rápido

Para agentes simples y cambios pequeños. Infiere la especificación del contexto, confírmala con el usuario, y construye. Sin entrevista completa, sin compuerta de aprobación separada.

No pienses demasiado en este nivel. Si estás inseguro, aún así empieza aquí — la complejidad surgirá durante la inferencia. Promueve si aparecen señales.

Criterios de Entrada

  • El agente es nuevo (1-2 capacidades) o existente con una modificación pequeña.
  • Sin integraciones externas más allá de las que ya existen.
  • Sin coordinación multi-agente.
  • Sin riesgo de seguridad, costo o cumplimiento.
  • Los requisitos son lo suficientemente claros como para que una entrevista de 8 dominios se sienta como sobreingeniería.

Proceso

1. Inferir especificación del contexto   ← Leer de lo que el usuario dijo + código base + agentes existentes
2. Presentar mini-especificación         ← Usar el formato fijo a continuación
3. Usuario marca                          ← "Dime dónde cambiar"
   Si la marca es trivial (1-2 palabras, corrige nombre/formato ligeramente)
     → Construir directamente
   Si la marca es estructural (agregar capacidad, cambiar herramienta, corregir límite)
     → presentar mini-especificación revisada primero → usuario confirma → Construir
4. Construir

Formato de Mini-Especificación (Fijo)

## Especificación Rápida: [Nombre]

Tarea: [Una oración — "hace qué, para quién, para lograr qué"]
Capacidades:
  - [acción 1]
  - [acción 2]
Límites:
  - [qué no debe hacer]
Autoridad: [Solo lectura / Sugerir / Modificar dentro del alcance / Ejecutar / Autónomo]
Herramientas: [herramienta / MCP / ninguna necesaria]
Aprobación: [Confirmado vía Rápido / Revisado y Confirmado]

Usa el archivo templates/quick-spec.md como plantilla real. No acortes ni omitas estos campos — si un campo es obvio, escribe "—" (no preguntes al usuario). Si modificas un agente existente → usa el mismo formato, pero muestra solo los campos que cambian.

Ejemplo

Usuario: "Quiero un agente que resuma mis correos"

Inferir:
  Arquetipo: Escriba
  Capacidad: leer correo electrónico → resumen con viñetas
  Herramientas: Gmail MCP (ya existe)
  Ecosistema: vive con steward

Presentar mini-especificación:
  ## Especificación Rápida: mail-summarizer

  Tarea: Leer Gmail → resumir en viñetas para Mike cada mañana
  Capacidades:
    - Leer correos de Gmail MCP → resumir como viñetas
    - Separar por remitente / asunto
  Límites:
    - No responder correos, no eliminar correos
  Autoridad: Solo lectura (leer únicamente)
  Herramientas: Gmail MCP (ya existe)
  Aprobación: —

  "¿En español o inglés? ¿Todos los correos o solo ciertos temas?"

Usuario: "Español, todos, sin registrar"
  (marca trivial — enviar a Construir)

Construir.
  ## Especificación Rápida: mail-summarizer
  ...
  Autoridad: Solo lectura
  Aprobación: Confirmado vía Rápido

Nivel 2 — Estándar

Para agentes nuevos y cambios significativos. Promueve a Estándar cuando Rápido es insuficiente (integraciones complejas, impacto en el ecosistema o alcance poco claro).

Proceso

1. Compuerta de Intención    → Reformular, identificar arquetipo, usuario + objetivo + restricción
2. Escaneo del Código Base   → Leer index.md, opencode.jsonc, AGENTS.md, agentes existentes
                              (si no hay → greenfield: saltar, ir a presentar borrador directamente)
3. Coincidencia de Arquetipo → Seleccionar arquetipo, aplicar lista de minimización
4. Presentar Borrador        → Inferir especificación completa del contexto conocido → presentar borrador de 1 página
                              Preguntar solo sobre incertidumbres (no preguntar uno por uno)
5. Usuario Marca             → El usuario edita / agrega / elimina del borrador
6. Iterar (si es necesario)  → Si hay vacío → presentar borrador revisado
7. Proponer Especificación   → Especificación Completa del Agente (ver templates/agent-spec.md)
8. Compuerta de Aprobación   → El usuario aprueba antes de construir

Entrevista de Alcance (8 Dominios)

Para el nivel Rápido: Saltar todo — inferir + confirmar desde el principio.

Para Estándar+:

  1. Inferir borrador de especificación del contexto existente → presentar borrador de una página al usuario
  2. El usuario lee y marca (corrige/agrega/elimina)
  3. Usar la lista de verificación a continuación para comprobar si falta algo — preguntar solo sobre lo que el borrador no cubre
  4. Aplicar la Lista de Minimización de Arquetipos — breve / omitir si obvio / análisis profundo según arquetipo

No preguntes cada elemento de la lista de verificación en orden — presenta el borrador primero, pregunta solo sobre vacíos.

Dominio 1: Identidad y Propósito

  • Nombre — ¿cómo se llama el agente? (proponer si no tiene nombre)

  • Arquetipo — ¿qué arquetipo según el catálogo?

  • Rol — una oración clara: "Este agente [hace X] para [usuario Y] para que [Z]."

  • Persona —

    CampoQuéEjemplo
    Tonoformal / casual / técnico / juguetón / autoritario / cálido"técnico pero accesible"
    Frase de ejemploPalabras reales que dice el agente"Déjame revisar la configuración... Lo encontré. El problema está en la línea 42."

    Siempre recomienda una persona.

    "Sugiero un tono técnico pero accesible —
     preciso en los hechos, relajado en la conversación."
    
  • Contexto que conoce — ¿qué debe saber antes de trabajar?

  • Trabajo más específico — ¿cuál es la definición más pequeña y útil de su rol?

Dominio 2: Capacidades y Límites

  • Capacidades — acciones principales, ordenadas por prioridad. Cada capacidad incluye:

    • Descripción (1 oración)
    • Disparador (¿cómo se invoca esta capacidad?)
    • Salida esperada (¿cómo se ve el éxito?)
    • Modo de fallo (¿qué pasa si no funciona?)
  • Límites — lista explícita de lo que nunca debe hacer. Formatea cada uno como una Regla Crítica con escenario:

    Regla: Nunca modificar archivos fuera del directorio del proyecto.
    Escenario: El usuario pide "arregla la configuración de mi escritorio" — el agente tiene acceso al sistema de archivos.
    Consecuencia: Rechazar educadamente, explicar el límite del alcance.
    
  • Mapeo de Herramientas — para cada capacidad, determina qué herramientas se necesitan. Haz esto después de que las capacidades y los límites estén claros.

    Capacidad: "Buscar documentación"
    ↓
    Buscar en el código base herramientas existentes → encontró Exa MCP (búsqueda web)
    ↓
    Proponer: "Recuperación de conocimiento vía Exa MCP (ya configurado).
              Si Exa no está disponible, respaldo con búsqueda web vía Firecrawl."
    

    Regla: Propón una herramienta específica si ya existe una en el código base. Solo propón una categoría cuando ninguna herramienta existente sea adecuada. Pero: si la herramienta existente no coincide con los requisitos (por ejemplo, se necesita búsqueda en documentos locales pero solo existe Exa búsqueda web) — no la fuerces a encajar Márcala como encaje parcial o vacío y propón una categoría más adecuada.

    ✅ "Usa Exa MCP para búsqueda web — ya configurado"
    ✅ "Exa MCP existe para búsqueda web, pero la búsqueda en registros de trabajo debería usar
        Obsidian + grep en su lugar — es un encaje parcial para búsqueda externa"
    ✅ "No se encontró una base de datos vectorial existente. Necesita una herramienta de búsqueda semántica
        como Chroma o Qdrant."
    ❌ "Necesita una herramienta de recuperación de conocimiento" (vago — Exa existe, úsala)
    ❌ "Usa Exa MCP para todo" (forzado a encajar — Exa no es adecuado para búsqueda local)
    

    Categorías de herramientas (referencia para vacíos):

    Recuperación de conocimiento → búsqueda, bases de datos vectoriales, almacenes de documentos, scraping web
    Ejecución de código         → sandboxes, intérpretes, compiladores, linters
    Comunicación                → correo electrónico, mensajería, notificaciones, webhooks
    Operaciones del sistema     → E/S de archivos, gestión de procesos, red, registro
    Procesamiento de datos      → ETL, transformación, validación, almacenamiento
    Visual/creativo             → generación de imágenes, motores de diseño, animación
    Monitoreo                   → registros, métricas, trazado, alertas
    Inteligencia Artificial/LLM → APIs de modelos, incrustaciones, pipelines RAG, bases de datos vectoriales
    Pruebas                     → ejecutores de pruebas, cobertura, burla, navegadores E2E
    

[El contenido se ha truncado para la traducción; se puede continuar de manera similar para las secciones restantes]


*Nota: El contenido de `SKILL.md` original se ha truncado por limitaciones de longitud; la traducción sigue el mismo patrón para las secciones restantes (Dominios 3-8, Niveles 3 y 4, plantillas).*

Skills relacionados