Ir al contenido principal

Skills (Habilidades)

AI Cockpit - Reasoning implementa Agent Skills, un formato ligero y abierto para extender las capacidades de los agentes de IA con conocimiento especializado y flujos de trabajo.

¿Qué Son los Agent Skills?​

Los Agent Skills empaquetan experiencia de dominio, nuevas capacidades y flujos de trabajo repetibles que los agentes pueden usar. En esencia, una skill es una carpeta que contiene un archivo SKILL.md con metadatos e instrucciones que le indican a un agente cómo realizar una tarea específica.

Este enfoque mantiene a los agentes rápidos mientras les da acceso a más contexto bajo demanda. Cuando una tarea coincide con la descripción de una skill, el agente lee las instrucciones completas en el contexto y las sigue, cargando opcionalmente archivos referenciados o ejecutando código incluido según sea necesario.

Beneficios Clave​

  • Auto-documentado: El autor o usuario de una skill puede leer un archivo SKILL.md y entender qué hace, facilitando la auditoría y mejora de las skills
  • Interoperable: Las skills funcionan en cualquier agente que implemente la especificación de Agent Skills
  • Extensible: Las skills pueden variar en complejidad desde simples instrucciones de texto hasta scripts incluidos, plantillas y materiales de referencia
  • Compartible: Las skills son portátiles y se pueden compartir fácilmente entre proyectos y desarrolladores

Cómo Funcionan las Skills en AI Cockpit - Reasoning​

Las skills pueden ser:

  • Genéricas - Disponibles en todos los modos
  • Específicas de modo - Solo se cargan cuando se usa un modo particular (por ejemplo, code, architect)

El flujo de trabajo es:

  1. Descubrimiento: Las skills se escanean desde los directorios designados cuando AI Cockpit - Reasoning se inicializa. Solo se leen los metadatos (nombre, descripción y ruta del archivo) en esta etapa, no las instrucciones completas.
  2. Inclusión en el prompt: Cuando un modo está activo, los metadatos de las skills relevantes se incluyen en el prompt del sistema. El agente ve una lista de skills disponibles con sus descripciones.
  3. Carga bajo demanda: Cuando el agente determina que una tarea coincide con la descripción de una skill, lee el archivo SKILL.md completo en el contexto y sigue las instrucciones.

Cómo el Agente Decide Usar una Skill​

El agente (LLM) decide si usar una skill basándose en el campo description de la skill. No hay coincidencia de palabras clave ni búsqueda semántica: el agente evalúa su solicitud contra todas las descripciones de skills disponibles y determina si alguna "aplica de manera clara e inequívoca".

Esto significa:

  • La redacción de la descripción importa: Escriba descripciones que coincidan con cómo los usuarios formulan las solicitudes
  • La invocación explícita siempre funciona: Decir "usa la skill api-design" la activará ya que el agente ve el nombre de la skill
  • Las descripciones vagas llevan a coincidencias inciertas: Sea específico sobre cuándo se debe usar la skill

Ubicaciones de las Skills​

Las skills se cargan desde múltiples ubicaciones, permitiendo tanto skills personales como instrucciones específicas del proyecto.

Skills Globales (Nivel de Usuario)​

Las skills globales se encuentran en el directorio .aicockpitcode dentro de su directorio de inicio.

  • Mac y Linux: ~/.aicockpitcode/skills/
  • Windows: \Users\<suUsuario>\.aicockpitcode\
~/.aicockpitcode/
├── skills/                    # Skills genéricas (todos los modos)
│   ├── my-skill/
│   │   └── SKILL.md
│   └── another-skill/
│       └── SKILL.md
├── skills-code/              # Solo modo Code
│   └── refactoring/
│       └── SKILL.md
└── skills-architect/         # Solo modo Architect
    └── system-design/
        └── SKILL.md

Skills de Proyecto (Nivel de Espacio de Trabajo)​

Ubicadas en .aicockpitcode/skills/ dentro de su proyecto:

su-proyecto/
└── .aicockpitcode/
    ├── skills/               # Skills genéricas para este proyecto
    │   └── project-conventions/
    │       └── SKILL.md
    └── skills-code/          # Skills del modo Code para este proyecto
        └── linting-rules/
            └── SKILL.md

Skills Específicas de Modo​

Para crear una skill que solo aparezca en un modo específico:

# Solo para el modo Code
mkdir -p ~/.aicockpitcode/skills-code/typescript-patterns

# Solo para el modo Architect
mkdir -p ~/.aicockpitcode/skills-architect/microservices

El patrón de nomenclatura del directorio es skills-{mode-slug} donde {mode-slug} coincide con el identificador del modo (por ejemplo, code, architect, ask, debug).

Prioridad y Anulaciones​

Cuando múltiples skills comparten el mismo nombre, AI Cockpit - Reasoning usa estas reglas de prioridad:

  1. Las skills de proyecto anulan las skills globales - Una skill de proyecto con el mismo nombre tiene precedencia
  2. Las skills específicas de modo anulan las skills genéricas - Una skill en skills-code/ anula la misma skill en skills/ cuando está en el modo Code

Esto le permite:

  • Definir skills globales para uso personal
  • Anularlas por proyecto cuando sea necesario
  • Personalizar el comportamiento para modos específicos

Cuándo Se Cargan las Skills​

Las skills se descubren cuando AI Cockpit - Reasoning se inicializa:

  • Cuando VSCode se inicia
  • Cuando recarga la ventana de VSCode (Cmd+Shift+P → "Developer: Reload Window")

Los directorios de skills se monitorean para detectar cambios en los archivos SKILL.md. Sin embargo, la forma más confiable de incorporar nuevas skills es recargar VS Code o la extensión AI Cockpit - Reasoning.

Agregar o modificar skills requiere recargar VSCode para que los cambios surtan efecto.

Puede crear symlinks de directorios de skills para compartir skills entre máquinas o desde un repositorio central. Al usar symlinks, el campo name de la skill debe coincidir con el nombre del symlink, no con el nombre del directorio de destino.

Formato de SKILL.md​

El archivo SKILL.md usa frontmatter YAML seguido de contenido Markdown que contiene las instrucciones:

---
name: my-skill-name
description: Una breve descripción de lo que hace esta skill y cuándo usarla
---

# Instrucciones

Sus instrucciones detalladas para el agente de IA van aquí.

El agente leerá este contenido cuando decida usar la skill basándose en
su solicitud que coincida con la descripción anterior.

## Ejemplo de Uso

Puede incluir ejemplos, pautas, fragmentos de código, etc.

Campos del Frontmatter​

Según la especificación de Agent Skills:

CampoRequeridoDescripción
nameSíMáx. 64 caracteres. Solo letras minúsculas, números y guiones. No debe comenzar ni terminar con guión.
descriptionSíMáx. 1024 caracteres. Describe qué hace la skill y cuándo usarla.
licenseNoNombre de la licencia o referencia a un archivo de licencia incluido
compatibilityNoRequisitos del entorno (producto previsto, paquetes del sistema, acceso a red, etc.)
metadataNoMapeo arbitrario de clave-valor para metadatos adicionales

Ejemplo con Campos Opcionales​

---
name: pdf-processing
description: Extraer texto y tablas de archivos PDF, rellenar formularios, combinar documentos.
license: Apache-2.0
metadata:
    author: example-org
    version: 1.0.0
---

## Cómo extraer texto

1. Use pdfplumber para la extracción de texto...

## Cómo rellenar formularios

...

Regla de Coincidencia de Nombres​

En AI Cockpit - Reasoning, el campo name debe coincidir con el nombre del directorio padre:

✅ Correcto:
skills/
└── frontend-design/
    └── SKILL.md  # name: frontend-design

❌ Incorrecto:
skills/
└── frontend-design/
    └── SKILL.md  # name: my-frontend-skill  (¡no coincide!)

Recursos Incluidos Opcionales​

Si bien SKILL.md es el único archivo requerido, puede incluir opcionalmente directorios adicionales para apoyar su skill:

my-skill/
├── SKILL.md           # Requerido: instrucciones + metadatos
├── scripts/           # Opcional: código ejecutable
├── references/        # Opcional: documentación
└── assets/            # Opcional: plantillas, recursos

Estos archivos adicionales pueden ser referenciados desde las instrucciones de su skill, permitiendo al agente leer documentación, ejecutar scripts o usar plantillas según sea necesario.

Ejemplo: Crear una Skill​

  1. Cree el directorio de la skill:

    mkdir -p ~/.aicockpitcode/skills/api-design

  2. Cree SKILL.md:

    ---
    name: api-design
    description: Mejores prácticas y convenciones de diseño de API REST
    ---

    # Pautas de Diseño de API

    Al diseñar APIs REST, siga estas convenciones:

    ## Estructura de URL

    - Use sustantivos en plural para recursos: `/users`, `/orders`
    - Use kebab-case para recursos de varias palabras: `/order-items`
    - Anide recursos relacionados: `/users/{id}/orders`

    ## Métodos HTTP

    - GET: Recuperar recursos
    - POST: Crear nuevos recursos
    - PUT: Reemplazar recurso completo
    - PATCH: Actualización parcial
    - DELETE: Eliminar recurso

    ## Códigos de Respuesta

    - 200: Éxito
    - 201: Creado
    - 400: Solicitud incorrecta
    - 404: No encontrado
    - 500: Error del servidor

  3. Recargue VSCode para cargar la skill

  4. La skill estará disponible en todos los modos

Encontrar Skills​

Puede descubrir e instalar skills creadas por la comunidad a través de:

  • AI Cockpit Marketplace - Explore skills directamente en la extensión AI Cockpit - Reasoning a través de la pestaña Marketplace
  • Especificación de Agent Skills - La especificación abierta que siguen las skills, habilitando la interoperabilidad entre diferentes agentes de IA

Solución de Problemas​

¿La Skill No Se Carga?​

  1. Verifique el panel de Salida: Abra Ver → Salida → Seleccione "AI Cockpit - Reasoning" del menú desplegable. Busque errores relacionados con skills.

  2. Verifique el frontmatter: Asegúrese de que name coincida exactamente con el nombre del directorio y que description esté presente.

  3. Recargue VSCode: Las skills se cargan al inicio. Use Cmd+Shift+P → "Developer: Reload Window".

  4. Verifique la ubicación del archivo: Asegúrese de que SKILL.md esté directamente dentro del directorio de la skill, no anidado más profundo.

Verificar que una Skill Está Disponible​

Para confirmar que una skill está correctamente cargada y disponible para el agente, puede preguntarle directamente al agente. Simplemente envíe un mensaje como:

  • "¿Tienes acceso a la skill X?"
  • "¿Está cargada la skill llamada X?"
  • "¿Qué skills tienes disponibles?"

El agente responderá con información sobre si la skill está cargada y accesible. Esta es la forma más confiable de verificar que una skill está disponible después de agregarla o recargar VSCode.

Verificar si se Usó una Skill​

Para ver si se usó realmente una skill durante una conversación, busque una llamada a la herramienta read_file en el chat que apunte a un archivo SKILL.md. Cuando el agente decide usar una skill, lee el archivo completo de la skill en el contexto, lo que aparece como una operación de lectura de archivo en la conversación.

Actualmente no hay un indicador de interfaz de usuario dedicado que muestre "Se activó la Skill X". La llamada a read_file es la forma más confiable de confirmar que se usó una skill.

Errores Comunes​

ErrorCausaSolución
"falta el campo requerido 'name'"No hay name en el frontmatterAgregue name: nombre-de-su-skill
"el nombre no coincide con el directorio"Discrepancia entre frontmatter y nombre de carpetaHaga que name coincida exactamente
La skill no apareceEstructura de directorio incorrectaVerifique que la ruta siga skills/nombre-skill/SKILL.md

Relacionado​