Objetivo del tema
Comprender cómo extender y adaptar Qwen Code mediante skills e instrucciones reutilizables, y cómo crear comandos personalizados para encapsular flujos repetitivos, prompts frecuentes o procesos específicos de un proyecto o de un equipo.
Este tema se apoya en la documentación oficial disponible al 11 de abril de 2026, especialmente en Agent Skills y en Commands dentro de Qwen Code Docs.
Una de las limitaciones de cualquier agente generalista es que, si siempre se le pide todo desde cero, el usuario termina repitiendo las mismas instrucciones una y otra vez. Las skills existen para resolver eso.
La documentación oficial las describe como capacidades modulares que amplían la efectividad del modelo mediante carpetas organizadas que contienen instrucciones y, opcionalmente, scripts, plantillas o documentación de apoyo.
En términos prácticos, una skill sirve para:
Una skill no es un simple archivo de notas. Es una forma de convertir conocimiento operativo en una capacidad reutilizable para Qwen Code.
La documentación oficial define cada skill como una carpeta que contiene al menos un archivo obligatorio: SKILL.md.
Ese archivo incluye:
Ejemplo mínimo documentado:
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---
# Your Skill Name
## Instructions
Provide clear, step-by-step guidance for Qwen Code.
## Examples
Show concrete examples of using this Skill.
En castellano, la idea sería la misma: un nombre claro, una descripción específica y una guía reutilizable que el agente pueda cargar cuando corresponde.
La documentación oficial marca una diferencia central: las skills son model-invoked. Es decir, el modelo decide autónomamente cuándo usarlas si la petición del usuario coincide con la descripción de la skill.
Esto las diferencia de los slash commands:
| Mecanismo | Quién lo activa | Propósito principal |
|---|---|---|
| Skill | El modelo, automáticamente | Aplicar experiencia especializada cuando detecta una coincidencia. |
| Slash command | El usuario, explícitamente | Controlar la sesión o ejecutar una acción concreta. |
Si querés forzar una skill de manera explícita, la documentación indica el uso de:
/skills
/skills nombre-de-la-skill
Esto permite listar las disponibles o invocar una en particular cuando querés asegurar su uso.
Qwen Code distingue tres orígenes principales para skills:
| Tipo | Ubicación | Uso recomendado |
|---|---|---|
| Personal | ~/.qwen/skills/ |
Preferencias individuales, experimentación o ayudas personales. |
| Proyecto | .qwen/skills/ |
Convenciones compartidas, experiencia del dominio y flujos del equipo. |
| Extensión | Dentro del directorio de la extensión | Capacidades empaquetadas como parte de una extensión instalada. |
La ventaja de las skills de proyecto es muy grande: pueden versionarse con Git y distribuirse al equipo junto con el repositorio.
La documentación muestra que una skill puede ir mucho más allá de un único archivo. Una estructura típica sería esta:
mi-skill/
├── SKILL.md
├── reference.md
├── examples.md
├── scripts/
│ └── helper.py
└── templates/
└── template.txt
Esto significa que la skill no solo puede describir un flujo, sino también traer consigo materiales de apoyo reales:
Desde el punto de vista pedagógico, esto convierte a las skills en pequeñas “cajas de herramientas” especializadas.
La documentación oficial insiste en dos requisitos obligatorios:
name debe ser un string no vacíodescription debe ser un string no vacíoPero además recomienda convenciones importantes:
Ejemplo de descripción vaga:
description: Helps with documents
Ejemplo de descripción mejor:
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction.
La lección es clara: si la descripción no es específica, el modelo tendrá menos señales para saber cuándo usar la skill.
Conviene pensar esta distinción del mismo modo que en la configuración:
Ejemplos típicos de skills personales:
Ejemplos típicos de skills de proyecto:
La documentación recomienda probar una skill haciendo preguntas que coincidan con su descripción. Si la descripción menciona PDF, por ejemplo, una consulta relacionada con PDFs debería dispararla naturalmente.
También recomienda usar qwen --debug para ver errores de carga cuando algo no funciona como se espera.
qwen --debug
Este modo de depuración es especialmente útil para diagnosticar:
La documentación oficial indica varias formas de descubrir qué skills tenés disponibles.
/skills
ls ~/.qwen/skills/
ls .qwen/skills/
cat ~/.qwen/skills/mi-skill/SKILL.md
Esto es útil tanto para inspección manual como para diagnóstico. Muchas veces el problema no es que la skill “no funcione”, sino que en realidad no fue ubicada en la carpeta correcta.
Además de las skills, la documentación de Commands describe otra herramienta muy útil: los custom commands. A diferencia de las skills, estos sí son user-invoked, es decir, el usuario los llama de manera explícita como atajos con slash.
Su objetivo es encapsular prompts frecuentes, flujos repetitivos o acciones consistentes en un comando corto y recordable.
La documentación actual indica que estos comandos ahora usan Markdown con YAML frontmatter opcional. El formato viejo en TOML está deprecado, aunque sigue siendo soportado por compatibilidad.
La documentación oficial distingue dos niveles principales:
| Tipo | Ruta | Prioridad |
|---|---|---|
| Global | ~/.qwen/commands/ |
Baja |
| Proyecto | <project>/.qwen/commands/ |
Alta |
La regla de prioridad documentada es muy clara: los comandos de proyecto sobrescriben a los de usuario si tienen el mismo nombre.
La documentación de Commands explica que los subdirectorios generan namespaces separados por dos puntos en el nombre del comando.
Ejemplo:
.qwen/commands/git/commit.md
Se convierte en:
/git:commit
Esto permite organizar mejor los atajos cuando un proyecto ya tiene muchos comandos personalizados.
La documentación explica que el cuerpo Markdown del archivo actúa como prompt reutilizable. Un ejemplo conceptual sería:
---
description: Redacta un mensaje de commit breve y claro
---
Analiza los cambios actuales y genera un mensaje de commit conciso.
Guardado como:
.qwen/commands/git/commit.md
Se invocaría como:
/git:commit
La ventaja es obvia: en lugar de redactar el mismo prompt una y otra vez, lo encapsulás en un comando fijo.
Conviene dejar esta comparación muy clara porque ambos mecanismos extienden el comportamiento de Qwen Code, pero no cumplen el mismo papel.
| Aspecto | Skill | Custom command |
|---|---|---|
| Activación | Automática por parte del modelo | Explícita por parte del usuario |
| Objetivo | Aportar capacidad especializada | Crear atajos reutilizables |
| Formato principal | SKILL.md |
Markdown en .qwen/commands/ |
| Uso típico | Procesamiento de PDFs, flujos especializados, conocimientos compartidos | Prompts frecuentes, acciones recurrentes, shortcuts de equipo |
Una forma simple de recordarlo es esta: las skills hacen al agente más competente; los custom commands hacen al usuario más rápido.
Algunas reglas prácticas suelen funcionar bien:
Ejemplos:
/git:commit para redactar commits./docs:release para generar release notes.La documentación oficial insiste en varias recomendaciones que vale la pena convertir en regla de trabajo:
Estas prácticas reducen la deriva de complejidad y hacen que el sistema siga siendo usable a medida que crece.
La mayoría de los problemas vienen de metadatos vagos, ubicaciones incorrectas o expectativas equivocadas sobre el mecanismo usado.
| Problema | Causa probable | Primer paso razonable |
|---|---|---|
| La skill no se activa | Descripción demasiado vaga o ruta incorrecta. | Revisar SKILL.md y su ubicación real. |
| La metadata no carga | Frontmatter YAML inválido. | Validar sangría, delimitadores --- y sintaxis. |
| El comando personalizado no aparece | Se guardó fuera de .qwen/commands/ o en formato incorrecto. |
Verificar ruta, extensión y frontmatter. |
| Una capability parece duplicada | Se mezcló skill con custom command para el mismo problema. | Decidir si la necesidad es activación automática o atajo explícito. |
Qwen Code no se limita a sus funciones integradas: puede extenderse mediante skills y mediante comandos personalizados. Las skills encapsulan conocimiento especializado que el agente puede usar automáticamente; los custom commands encapsulan atajos explícitos para el usuario.
En este tema vimos las ideas centrales:
SKILL.md y, opcionalmente, archivos de apoyo..qwen/commands/ y funcionan como atajos explícitos.Con esta base, el siguiente paso natural es estudiar los subagentes, que permiten dividir tareas complejas en agentes especializados con roles más acotados.