VS Code: crear y usar Skills

Este tutorial te guiará para crear un Agent Skill desde cero y ejecutarlo realmente en VS Code + GitHub Copilot.

Crearemos un Skill de lanzamiento de dados para que el Agent aprenda a generar números aleatorios mediante comandos de terminal.


Preparación

Requisitos del entorno

Este tutorial usa VS Code, pero Agent Skills es un formato abierto. El mismo Skill también se puede usar en herramientas compatibles como Claude Code, OpenCode, OpenAI Codex, etc.

Puedes consultar más contenido de VS Code en:Tutorial de VS Code。


Crear el directorio y los archivos del Skill

VS Code, por defecto, en el directorio del proyecto.agents/skills/busca el Skill en dicho directorio.

Primero, crea la siguiente estructura de directorios en tu proyecto:

Crear la estructura de directorios

# Ejecutar en el directorio raíz del proyecto
mkdir -p .agents/skills/roll-dice

Luego, en.agents/skills/roll-dice/SKILL.mdcrea los siguientes archivos:

Ejemplo: contenido completo de SKILL.md

---
name: roll-dice
description:Lanza dados usando un generador de números aleatorios. Úsalo cuando el usuario pida lanzar dados (d6, d20, etc.) o generar un valor aleatorio de dados.
---

# Método para lanzar dados

Usa el siguiente comando de shell para generar1un número aleatorio entre 1 y el número de caras especificado:

## macOS / Linux

```bash
echo $((RANDOM % <sides> + 1))
```

## Windows PowerShell

```powershell
Get-Random -Minimum 1 -Maximum (<sides> + 1)
```

**Instrucciones de uso:**
Reemplaza `<sides>` por el número de caras del dado especificado por el usuario:
-d6: reemplaza `<sides>` por6
-d20: reemplaza `<sides>` por20
-Para otros números de caras, sigue el mismo procedimiento.

**Salida:**Devuelve directamente el número de resultado aleatorio, sin explicaciones adicionales.

Con un solo archivo y menos de 20 líneas, tienes un Skill completo.


Análisis de la estructura del archivo

Entendamos la función de este archivo parte por parte.

Encabezado YAML (Frontmatter)

CampoFunciónDescripción
nameIdentificador único del SkillDebe coincidir exactamente con el nombre de la carpeta, utilizando letras minúsculas y guiones.
descriptionDescripción de la condición de activaciónIndica al Agent cuándo debe usar este Skill; es el campo clave para que el Agent decida si activarlo.

Cuerpo (Markdown Body)

El cuerpo son las instrucciones que el Agent sigue realmente después de activar el Skill.

Aquí le decimos al Agent: cuando el usuario pida lanzar dados, usa el comando de números aleatorios del sistema operativo y pasa el número de caras del dado al comando.

También proporcionamos comandos para las dos plataformas, macOS/Linux y Windows. El Agent elegirá automáticamente según el entorno actual.


Prueba tu Skill

Después de crear el archivo, verifícalo siguiendo los siguientes pasos:

  1. Abre tu proyecto con VS Code

  2. Abre el panel de Copilot Chat (atajo Ctrl+Shift+I o Cmd+Shift+I), o haz clic en el botón de la esquina superior derecha:

  3. En la parte inferior del panel de chat, selecciona elAgentmodo
  4. Ingresa el/skillscomando y confirma que roll-dice aparece en la lista de Skills.

  5. Puedes ver que la lista de Skills contiene roll-dice:

Si no ves roll-dice en la lista de /skills, verifica que la ruta del archivo sea correcta:.agents/skills/roll-dice/SKILL.md; ten en cuenta que SKILL.md debe estar en mayúsculas.

Una vez que hayas confirmado que el Skill se ha cargado, escribe en el chat:

Roll a d20

El Agent debería activar automáticamente el Skill roll-dice, ejecutar el comando de terminal y devolver un número aleatorio entre 1 y 20.


El proceso de trabajo en segundo plano

Cuando usas este Skill en Copilot Chat, internamente se llevan a cabo tres pasos:

Paso 1: Descubrimiento

Al comenzar la sesión de chat, el Agent escanea el directorio de Skills predeterminado (.agents/skills/) y encuentra roll-dice.

Solo lee name y description, y sabe que "este Skill se usa para lanzar dados".

Paso 2: Activación

Cuando escribes "Roll a d20", el Agent compara tu pregunta con la description de roll-dice.

Cuando la coincidencia es exitosa, el Agent carga el contenido completo de SKILL.md en el contexto.

Paso 3: Ejecución

El Agent, siguiendo las instrucciones del cuerpo, identifica que usas macOS (o Linux) y selecciona el comando bash.

Reemplaza el 20 correspondiente a d20 en el comando, ejecutaecho $((RANDOM % 20 + 1)), y luego te devuelve el resultado.


Solución de problemas comunes

ProblemaPosible causaSolución
La lista de /skills está vacíaLa ruta del archivo SKILL.md es incorrectaConfirma que el archivo está en el directorio .agents/skills/roll-dice/ del proyecto
El Agent no ejecuta el comandoDiferencias en la fiabilidad de las llamadas a herramientas del modeloIntenta cambiar de modelo, o sé más explícito: "ayúdame a lanzar un d20"
Error al ejecutar el comandoDiferencias en el entorno de ShellConfirma que el comando $RANDOM se ejecuta correctamente en la terminal de macOS/Linux

Consejos de uso en múltiples herramientas

Aunque este tutorial usa VS Code, el Skill también se puede usar en otras herramientas:

HerramientaUbicación del Skill
VS Code + Copilot.agents/skills/ o .github/copilot/
Claude Code.claude/skills/ o ~/.claude/skills/
OpenAI Codex.codex/skills/

Las diferentes herramientas pueden usar diferentes directorios predeterminados, pero el formato y la estructura de archivos del Skill en sí son universales.

Otras extensiones