Crea tu primera skill: revisa documentos y comprueba que se usa

Vamos a preparar una skill que compare un anuncio con una ficha de referencia y devuelva una revisión sin editar los originales. Es un procedimiento concreto: localizar diferencias, mostrar su evidencia y conservar los datos correctos.

Incluimos los archivos y una pauta para evaluarlo. También documentamos un intento con Codex CLI que quedó bloqueado al leerlos: no presentamos esa ejecución como una revisión completada. Sirve para mostrar por qué guardar una skill y conseguir que se aplique son pasos distintos.

Qué necesitas antes de empezar

• Un cliente compatible con skills locales: Codex CLI o su extensión, Claude Code, o Copilot en VS Code según su configuración.
• Una carpeta de trabajo con documentos de ejemplo y permiso para leerlos desde ese cliente.
• Un editor de texto para guardar Markdown. No necesitas programar ni añadir un servidor MCP para este ejercicio.

Usa tu acceso habitual al asistente. La skill de este ejemplo contiene instrucciones de texto; no incluye una API key, instalador ni comandos que publiquen contenido. Mantiene las condiciones de acceso y uso del cliente donde la ejecutes.

Puedes descargar los archivos del ejemplo y consultar su README, o copiar los fragmentos de esta página. El paquete contiene material ficticio y una pauta editorial; no contiene una salida exitosa obtenida del asistente.

Elige un procedimiento que vayas a repetir

Una revisión puntual puede resolverse con una petición clara y los dos documentos. La skill tiene sentido si quieres repetir siempre el mismo método: comparar, clasificar incidencias, justificar cambios y conservar información válida.

No necesitas convertir una preferencia como «responde en español» en un procedimiento entero. Si tu problema es decidir dónde guardar contexto permanente, consulta la guía de proyectos, memoria e instrucciones.

Crea el archivo SKILL.md

Llama a la carpeta revisar-documento y guarda dentro este archivo como SKILL.md, respetando mayúsculas y delimitadores:

---
name: revisar-documento
description: Contrasta un borrador con una ficha de referencia y devuelve incidencias localizadas. Úsala para revisar documentos con ambas entradas disponibles; no para investigar en Internet ni publicar.
---

# Revisar un documento

1. Identifica el borrador y la ficha de referencia indicados por el usuario.
   Si falta una entrada, indícalo antes de evaluar datos.
2. Lee ambos archivos. Distingue una contradicción con la referencia de una
   afirmación que la referencia no respalda. No inventes información.
3. Devuelve una tabla con fragmento, tipo de incidencia, evidencia en la ficha
   y corrección propuesta. Usa citas breves o números de línea.
4. Enumera los datos correctos que deben conservarse. No conviertas la ausencia
   de evidencia en una acusación de falsedad.
5. No edites ni publiques los archivos. Limita la revisión al material dado;
   no afirmes haber verificado fuentes externas.

El bloque inicial identifica el procedimiento y cuándo resulta pertinente; el cuerpo explica cómo hacerlo. El ejemplo usa name y description, campos requeridos por la especificación Agent Skills. El nombre coincide con la carpeta. Evita añadir de entrada campos exclusivos de un cliente si no los necesitas.

Estas instrucciones expresan el comportamiento esperado. No sustituyen los permisos del entorno ni garantizan que cada respuesta siga todos los pasos. Por eso la comprobación forma parte del tutorial.

Guárdala en la ruta de tu cliente

Copia la carpeta revisar-documento a una ubicación de proyecto compatible. Deja referencia.md y borrador.md en la raíz de la carpeta de trabajo. Elige la fila del cliente que realmente abrirás:

Las rutas y formas de invocación proceden de OpenAI, Claude Code y VS Code, consultadas el 17 de octubre de 2026. VS Code también admite otras ubicaciones, pero no necesitas duplicar la carpeta para seguir este ejercicio.

La fila de Copilot se refiere a ese cliente en VS Code. Una sesión de Codex integrada mediante Agent Host, la extensión nativa de Codex y Copilot no son intercambiables por compartir editor. Esta tabla es documental; no ejecutamos la skill en Claude Code ni Copilot.

En Codex, para el ejemplo, la estructura queda así:

mi-carpeta/
├── .agents/
│   └── skills/
│       └── revisar-documento/
│           └── SKILL.md
├── referencia.md
└── borrador.md

Prepara un ejemplo cuyo resultado puedas comprobar

Usa estos datos del taller ficticio, incluidos completos en la descarga:

Para Codex, escribe en su conversación:

$revisar-documento Revisa borrador.md usando referencia.md.
No edites los archivos. Devuelve las incidencias y los datos que conservarías.

En Claude Code, sustituye el comienzo por /revisar-documento. En Copilot, selecciona la skill desde el menú / y añade el encargo. Son mensajes para el asistente: no pegues $revisar-documento como un comando de PowerShell.

Comprueba disponibilidad, carga y resultado por separado

1. Disponible: ¿aparece en el selector o en las personalizaciones del cliente? Si no aparece, comprueba la carpeta abierta, la ruta y el nombre. Un archivo guardado en otro proyecto no demuestra disponibilidad aquí.
2. Cargada: ¿hay evidencia de que el cliente o sus herramientas leyeron el procedimiento? Una frase como «usaré tu skill» solo es una declaración. Revisa la actividad disponible y cualquier error de lectura.
3. Aplicada: ¿la respuesta detecta la fecha incorrecta y la garantía, cita la ficha y conserva horario y cupo? Si solo produce una tabla genérica, el formato no demuestra que la revisión sea correcta.

Si el registro del cliente no permite observar la carga, deja ese punto como no verificado. Puedes evaluar la respuesta, pero no atribuir su calidad al archivo sin más evidencia. Este primer ejercicio usa invocación explícita; no demuestra que el asistente vaya a seleccionarla automáticamente en otro encargo.

Qué ocurrió en nuestro intento con Codex

El 4 de octubre de 2026 ejecutamos una sesión de Codex CLI 0.159.2 con esta skill y los dos archivos, en una carpeta temporal sin Git. Usamos sesión efímera, sandbox de solo lectura, aprobación configurada en never y omisión del archivo de configuración de usuario. Estas condiciones no equivalen a todas las configuraciones normales de Codex.

El registro muestra intentos de leer SKILL.md, borrador.md y referencia.md, rechazados por una política del entorno. No se completó la revisión ni se verificó la aplicación de la skill. El proceso terminó con código 0 y los hashes de entrada no cambiaron: terminar el proceso y conservar archivos no demostraron éxito de la tarea.

No identificamos qué capa concreta originó esa restricción. Tampoco demuestra que el archivo de skill sea incorrecto o que un sandbox de solo lectura siempre impida leer. Conservamos el intento fallido y no ampliamos permisos para convertirlo en un resultado favorable.

La tabla anterior es la pauta preparada por comparación directa de los documentos; no es una respuesta atribuida a Codex. Las instrucciones para Claude Code y Copilot se apoyan en documentación, sin ensayo equivalente.

Si la skill no aparece o la revisión se detiene

• No aparece: comprueba la ruta de proyecto, SKILL.md, los delimitadores YAML y que name coincida con revisar-documento. Revisa también si el cliente tiene deshabilitada esa personalización.
• Aparece, pero no hay evidencia de carga: prueba la invocación explícita en el cliente correcto y consulta su actividad. No confundas encontrar una carpeta con leer su contenido.
• La lectura es rechazada: revisa el mensaje concreto y los permisos de lectura autorizados para esos archivos. Añadir más instrucciones a la skill no concede acceso. En un entorno administrado puede requerirse que su responsable revise la política.
• Lee los archivos, pero inventa datos o omite una incidencia: compara con la pauta y ajusta un paso concreto del procedimiento. Conserva el fallo para comprobar si el siguiente intento lo corrige.

Pegar ambos documentos en el chat permite hacer otra revisión si ese acceso está permitido, pero sería otra condición de prueba: no acredita que la skill local se haya cargado. Empieza con una tarea pequeña y verificable; amplía el procedimiento cuando tengas una necesidad repetida y sepas qué parte realmente funcionó.