La respuesta corta
- 1Llámala por su nombre:
/skill-nameo$skill-name. Si se ejecuta, la instalación está bien. - 2¿No la encuentra? Revisa la carpeta.
SKILL.mdtiene que estar directamente en<skills folder>/<name>/. - 3¿Sigues atascado? Busca abajo lo que estás viendo.
Encuentra el problema en 30 segundos
Busca a la izquierda lo que ves y salta a la solución de la derecha.
Llamarla por su nombre falla
No está donde tu agente la busca. Consulta La Skill no aparece.
Se ejecuta por su nombre, pero no con una petición normal
Revisa la descripción o la configuración. Consulta La Skill no se activa.
Se ejecuta otra Skill
Dos descripciones se solapan. Consulta Se ejecuta la Skill equivocada.
Empieza y luego se detiene
Falta algo de lo que depende. Consulta Falla a medias.
Ejecuta la versión antigua
Hay una segunda copia o la sesión está desactualizada. Consulta Versión antigua.
La Skill no aparece en Claude Code, Codex o Cursor
Si una Skill no está en /skills ni en Customize → Skills, el agente no la ha cargado. Lo más habitual es que la carpeta esté en el lugar equivocado o un nivel más abajo de la cuenta.
| Causa probable | Solución |
|---|---|
La instalaste para Claude Code con la CLI de Skillry, pero omitiste --agent claude-code | Reinstálala con esa opción. Sin ella, la CLI usa ~/.agents/skills/ |
| El ZIP añadió un nivel de carpeta extra | Sube la carpeta interior un nivel. Claude Code necesita exactamente skills/<name>/SKILL.md |
Un error en el frontmatter, entre las líneas --- | Corrígelo. Codex y Cursor necesitan name y description, y en Cursor name debe coincidir con el nombre de la carpeta |
| El agente todavía no la ha detectado | Claude Code: /reload-skills. Codex: reinícialo dentro del repositorio. Cursor: abre un chat nuevo o recarga la ventana |
Codex en la app de escritorio de ChatGPT: $ no encuentra nada | Es un error conocido (openai/codex#28505). Revisa /skills, reinicia o prueba con una copia en ~/.codex/skills/ (aún no lo hemos probado) |
Para ver todas las carpetas que lee cada agente, consulta Ubicaciones de las Skills.
La Skill aparece, pero no se activa sola
El agente decide si usa una Skill leyendo su descripción. Si una Skill solo se ejecuta cuando la llamas por su nombre, o la descripción no encaja con cómo lo pides o hay una configuración que la frena.
- Prueba el prompt de ejemplo de la página de la Skill. Está escrito para encajar con la descripción.
- Revisa
paths. Limita el uso automático a los archivos que coinciden. - ¿Tienes muchas Skills instaladas? El agente acorta o descarta descripciones para que quepan todas, así que pon el uso principal al principio. Consulta Activación.
Se ejecuta otra Skill en su lugar
Cuando dos Skills instaladas describen la misma tarea, compiten, y el agente elige la que más se parece a tu petición. Normalmente significa que tienes dos Skills para un trabajo parecido o la misma Skill instalada dos veces.
| Qué está pasando | Solución |
|---|---|
| Una Skill parecida siempre gana | Llama a la que quieres por su nombre: /skill-name en Claude Code y Cursor, $skill-name en Codex. Llamarla por su nombre siempre ejecuta esa Skill. |
| Tus propias Skills se solapan | Acota cada descripción por entrada, público o resultado, para que cada una cubra una sola tarea. Consulta Activación. |
| El mismo nombre está instalado dos veces | Claude Code usa primero Enterprise, luego la personal y después la del proyecto. Codex puede mostrar las dos. Quédate con una sola copia. |
| Una Skill se pone en marcha aunque no la hayas pedido | Haz su descripción más concreta sobre cuándo usarla, para que deje de coincidir con peticiones que no tienen nada que ver. Luego llama por su nombre a la Skill que quieres. Consulta Activación. |
Empieza y luego falla a medias
Casi siempre es una dependencia que falta: una versión de Node.js incorrecta, o no hay Python, FFmpeg o clave de FAL. La página de la Skill indica lo que necesita, así que revisa eso primero:
Sigue ejecutando la versión antigua
Actualizaste la Skill, pero el agente sigue comportándose como antes. El motivo es uno de estos:
- Solo se reemplazó
SKILL.md. Reinstálala con--forceo reemplaza la carpeta entera. - Hay otra copia con el mismo nombre instalada en otro sitio. Elimínala.
- En Claude Code, una Skill que ya se ejecutó se queda como estaba durante el resto de esa conversación. Empieza una conversación nueva para que recoja tus cambios.
Para copias de seguridad y volver a una versión anterior, consulta Gestionar y actualizar.
Funciona en tu equipo, pero no en la nube
Las sesiones en la nube se ejecutan en otra máquina, así que una Skill que solo vive en tu computadora no viaja con ellas a menos que lo configures:
| Agente | Solución |
|---|---|
| Claude Code | Sesiones en la nube: haz commit de la Skill en .claude/skills/ o actívala en claude.ai. Cowork: actívala en claude.ai. |
| Codex | Las Skills independientes no llegan a ChatGPT en la web ni en el móvil. Distribúyela dentro de un plugin. |
| Cursor | Guárdala en ~/.cursor/skills/ y activa Settings → Agents → Context and Tools → Sync Skills for Cloud Agents. |
Mensajes de error de la CLI de Skillry
Busca el mensaje que mostró la CLI de Skillry y haz lo que indica la columna de la derecha.
| Ves esto | Haz esto |
|---|---|
| “Not logged in.” o “Session expired.” | Ejecuta npx --yes skillry-cli@latest login |
| “…already exists. Re-run with --force to replace it safely.” | Añade --force. Se hace una copia de seguridad de la versión anterior |
| “This Skill requires a paid plan.” | Revisa el precio de la Skill o tu plan |
| “--agent and --target cannot be used together.” | Elige solo una de las dos opciones |
| “Secure session storage is currently supported on macOS and Windows only.” | En Linux, usa el prompt de instalación o Descargar ZIP |
Preguntas frecuentes
¿Por qué no se carga mi Skill de Claude Code?
Normalmente está en ~/.agents/skills/ en lugar de ~/.claude/skills/, o hay un nivel de carpeta de más. Corrige la ruta y, si la carpeta es nueva, ejecuta /reload-skills.
¿Por qué mi Skill me pide una API key?
Usa un servicio de pago, que aparece en Costos externos en la página de la Skill. Configura la clave como indique ese servicio y nunca la pegues en el chat.
¿Cómo sé que la instalación funcionó?
Aparece en /skills (Customize → Skills en Cursor) y se ejecuta cuando la llamas por su nombre.
Fuentes
¿Te ha sido útil esta guía?