Skills de Claude Code a Codex y Copilot: qué debes adaptar
Si ya tienes una skill que te resulta útil, empieza por separar el procedimiento que quieres conservar de la configuración que lo hace funcionar en tu cliente. Copiar SKILL.md puede trasladar instrucciones y dejar atrás una referencia, una conexión o la regla que exigía invocación manual.
Aquí adaptarás un ejemplo pequeño: comparar un anuncio con una ficha y devolver incidencias sin editar los originales. Incluimos un antes/después con fallos intencionales y una comprobación de archivos reproducible. No ejecutamos esta adaptación en Claude Code, Codex ni Copilot; la prueba funcional queda descrita para que puedas hacerla en tu entorno.
Qué necesitas y qué vas a conservar
Para revisar el ejemplo basta un editor de texto. Puedes descargar el paquete de adaptación y abrir su README. Contiene material propio, documentos ficticios, el diff y resultados estáticos. No instala clientes ni incorpora credenciales.
Solo necesitarás acceso al asistente y permiso para leer los documentos si decides hacer la prueba funcional. El script de auditoría es opcional: requiere Python 3 y PyYAML ya disponibles; también puedes revisar los cambios manualmente.
La especificación Agent Skills define un directorio con SKILL.md, frontmatter YAML y un cuerpo Markdown. Su núcleo exige name y description; el nombre debe cumplir las reglas del formato y coincidir con la carpeta. Los recursos pueden viajar junto al procedimiento mediante referencias relativas. El campo opcional compatibility declara requisitos del entorno cuando existen; no los instala.
Divide tu paquete en tres partes antes de moverlo:
- Procedimiento: entradas, pasos, criterio de calidad y salida esperada.
- Recursos: pautas, ejemplos y scripts que el procedimiento necesita de verdad.
- Dependencias del cliente: rutas de descubrimiento, invocación, herramientas, conexiones y permisos.
Si lo que quieres trasladar es una preferencia permanente, como el idioma de respuesta, revisa primero la diferencia entre proyectos, memoria e instrucciones. Este ejercicio trata un procedimiento que se solicita para una tarea concreta.
Identifica el cliente de destino
Usa una ruta de proyecto para el ejemplo. La tabla muestra opciones documentadas, no instalaciones que hayamos probado:
Destino de la carpeta revisar-documento y solicitud explícita
| Cliente | Carpeta de proyecto | Cómo solicitarla |
|---|---|---|
| Claude Code | .claude/skills/revisar-documento/ | Inicia el mensaje con /revisar-documento |
| Codex nativo, CLI o extensión | .agents/skills/revisar-documento/ | Menciona $revisar-documento |
| Copilot en VS Code | .github/skills/revisar-documento/ | Abre el menú / y selecciona la skill |
Fuentes consultadas el 4 de octubre de 2026: Claude Code, OpenAI y VS Code.
VS Code también reconoce .claude/skills/ y .agents/skills/. Su integración de Codex mediante Agent Host, experimental, puede descubrir .github/skills/; esa ruta no debe confundirse con la de Codex nativo. Comprueba qué agente y tipo de sesión abriste. No dupliques el mismo procedimiento en todas las ubicaciones por precaución: puedes crear nombres repetidos y dificultar saber qué copia se utiliza.
Audita el paquete antes de copiarlo
Abre SKILL.md y sigue cada referencia. Estas preguntas permiten distinguir una adaptación pequeña de un trabajo que necesita revisar dependencias:
- ¿El nombre coincide con la carpeta? Comprueba también que la descripción explique cuándo usar el procedimiento.
- ¿Viajan los archivos necesarios? Una pauta mencionada pero ausente deja el método incompleto.
- ¿Hay rutas de otra máquina? Sustituye una ubicación personal por un recurso relativo o una entrada que el usuario deba indicar.
- ¿El cuerpo exige una herramienta por su nombre? Revisa qué capacidad necesita. Cambiar “usa Read” por “lee ambos archivos” evita depender de ese nombre, pero no aporta una herramienta de lectura al destino.
- ¿Qué controla la invocación? Conserva la intención —por ejemplo, solo manual— con la configuración documentada del cliente nuevo.
- ¿Depende de un script, servicio o contexto separado? Anota intérprete, archivos, acceso y comportamiento requerido antes de prometer que el paquete está listo.
Si tu skill forma parte de un plugin, inventaría por separado sus conexiones y demás componentes. Una copia del Markdown no configura una cuenta ni autentica un servicio.
Un antes/después con tres defectos intencionales
El paquete deriva de una skill propia de revisión documental. La versión antes/ fue alterada para este ejercicio: no es un fallo observado de ningún producto y no debes instalarla.
Creamos una carpeta revision-local con un nombre de skill incompatible con el núcleo, una referencia ausente y una ruta personal ficticia. También acoplamos el paso de lectura al nombre Read. En despues/revisar-documento/ corregimos esos elementos y añadimos la pauta de revisión:
- name: Revisar Documento
+ name: revisar-documento
-1. Identifica el borrador indicado por el usuario y usa la ficha
- `/Users/persona-ejemplo/Documents/referencia.md`.
+1. Identifica el borrador y la ficha de referencia indicados por el usuario.
-2. Usa la herramienta Read para leer ambos archivos.
+2. Lee ambos archivos.
Este es un extracto de los cambios. El diff completo muestra además el traslado de los campos de invocación al adaptador. El enlace references/pauta.md permanece: ahora apunta a un archivo incluido. La ruta absoluta del ejemplo no corresponde a una persona real.
Conserva la invocación manual
El núcleo de despues/ está separado de la configuración del cliente. Prepara ambos antes de instalarlo: usar solo ese núcleo omitiría el control manual que tenía el ejemplo inicial.
Para Claude Code y Copilot en VS Code, añade estas claves al frontmatter de la copia de destino:
disable-model-invocation: true
user-invocable: true
Ambos documentan actualmente esos nombres: la primera clave impide la selección automática y la segunda mantiene la invocación del usuario. No basta dejar el fragmento YAML en una carpeta auxiliar; debe formar parte del SKILL.md que usará el cliente. Claude Code y VS Code.
Para Codex nativo, conserva el núcleo y coloca este archivo en revisar-documento/agents/openai.yaml:
policy:
allow_implicit_invocation: false
OpenAI documenta que esta política desactiva la invocación implícita y conserva la explícita. Hemos comprobado la sintaxis y el valor del archivo; no hemos observado al cliente aplicar esta política. Configuración de skills de Codex.
Si tu skill lleva context: fork, revísalo como otra decisión de ejecución. Claude Code lo admite y VS Code también lo documenta como experimental, con habilitación específica. No lo etiquetes como exclusivo de Claude ni supongas comportamiento idéntico por compartir nombre. Nuestro ejemplo no lo necesita. Claude Code y VS Code.
Qué comprobamos en los archivos
La auditoría local aplica cinco reglas declaradas: mapa YAML legible; presencia de name y description; nombre ASCII coherente con la carpeta; enlaces Markdown simples a archivos incluidos; y detección de ciertos patrones de rutas personales o absolutas.
Resultados estáticos del ejemplo; no son resultados de los asistentes
| Caso | Resultado observado | Qué significa |
|---|---|---|
| Antes, con defectos sembrados | Tres reglas fallan; dos campos quedan en REVIEW | Detecta nombre/carpeta, referencia ausente y ruta ficticia; pide revisar los controles del cliente |
| Núcleo después | Pasan las cinco reglas | Esos defectos no aparecen en la copia revisada |
| Adaptadores | YAML legible y valores esperados | Los archivos expresan la política prevista; su aplicación queda pendiente |
| Controles del auditor | Un positivo y seis variaciones producen lo previsto | Las cinco alteraciones defectuosas activan su regla; añadir un campo de cliente produce REVIEW |
La comprobación se realizó en Windows 10, con Python 3.11.4 y PyYAML 6.0.1. Los resultados completos incluyen hashes, entorno y controles. Los originales usados como base y su ZIP conservaron sus hashes. El paquete incluye un manifiesto para comparar los archivos descargados.
Puedes repetir las dos comprobaciones desde la carpeta extraída:
python audit_skill.py antes/revision-local/SKILL.md
python audit_skill.py despues/revisar-documento/SKILL.md
La primera devuelve código 1 por los defectos intencionales; la segunda devuelve 0. Es un auditor pequeño, no el validador oficial ni una certificación de Agent Skills. Solo reconoce enlaces Markdown sencillos y los patrones de ruta documentados en el README. No valida todas las dependencias, permisos, herramientas ni la lógica del procedimiento. REVIEW significa que un campo requiere interpretación por cliente, no que sea inválido globalmente.
Prueba carga y resultado por separado en tu cliente
Después de preparar la copia de destino con su adaptador, abre tu cliente habitual en la carpeta de trabajo. Copia allí caso/borrador.md y caso/referencia.md; reserva caso/resultado-referencia.md para evaluar la respuesta, sin entregarlo como entrada al asistente.
Invoca explícitamente la skill por la vía de la tabla y añade:
Revisa borrador.md usando referencia.md. Devuelve incidencias con evidencia y los datos que conservarías. No edites los archivos.
Registra estos estados por separado:
- Disponibilidad: la skill aparece en el mecanismo de selección del cliente.
- Carga: el registro o la vista disponible muestra que se leyeron sus instrucciones. Que el asistente diga “la usé” no es evidencia suficiente por sí sola.
- Aplicación: la revisión sigue el procedimiento y accede a las dos entradas.
- Resultado: corrige el 6 al 5 de noviembre de 2026, retira o reformula la garantía de documentos sin errores y conserva el horario 10:00–11:30 y el cupo de 12 personas.
Esos datos proceden de comparar los documentos ficticios; son una pauta editorial esperada, no una salida obtenida de los asistentes. Un resultado correcto tampoco demuestra, por sí solo, la carga de la skill: el prompt podría bastar para resolver el ejemplo.
Para comprobar el control manual, prueba después una petición equivalente sin nombrar la skill y observa si se carga. Una respuesta pertinente no demuestra carga automática; usa la evidencia que ofrezca el cliente. Un caso sin carga tampoco garantiza el control en todas las tareas.
Anota cliente, versión, agente, permisos, entrada y salida. Si una lectura está denegada o no puedes observar una etapa, márcala BLOQUEADA o NO COMPROBADA y conserva el motivo. No amplíes permisos solo para producir una prueba favorable. En el ejercicio de esta página, disponibilidad, carga, aplicación y resultado en los tres clientes quedan NO PROBADOS.
Mantén una fuente común y adapta solo lo necesario
Una organización posible es conservar el procedimiento y sus recursos en una fuente común, con adaptadores pequeños por cliente. Al cambiar un paso, vuelve a revisar el diff y el caso de referencia. Esta es una propuesta de mantenimiento; sincronizar archivos no verifica herramientas, autenticación ni políticas.
Si el motivo para usar un contexto separado es el tamaño del material, revisa también qué cabe en una ventana de contexto. Elegir esa opción merece una prueba propia: no la añadas solo porque el cliente reconozca el campo.
Da la adaptación por preparada cuando los archivos estén completos y cada dependencia tenga una decisión. Da la prueba funcional por terminada solo para el cliente, configuración y caso que realmente hayas observado.