# Portar una skill: ejemplo de adaptación de archivos

Material propio de Ranquia, derivado de la skill revisar-documento del tutorial
«Crea tu primera skill». Datos del taller ficticios. Revisión: 4 de octubre de 2026.
No se ejecutó esta adaptación en Claude Code, Codex ni Copilot.

## Para empezar sin ejecutar código

1. Abre `antes/revision-local/SKILL.md`: los defectos son intencionales.
2. Compáralo con `despues/revisar-documento/SKILL.md` y `cambios.diff`.
3. Comprueba la carpeta, nombre, referencia incluida y eliminación de ruta personal ficticia.
4. Lee «Conservar la invocación manual» antes de copiar el núcleo al cliente.
5. Revisa `resultados.json`; PASS_LIMITED_CHECKS no certifica compatibilidad.

`antes/` es un control negativo didáctico: no lo instales. `despues/` contiene el
procedimiento y una pauta genérica; no incluye por sí solo la política manual.
Los campos de cliente se clasifican REVIEW, no inválidos globalmente.

## Conservar la invocación manual

Elige una sola ubicación y prepara allí el núcleo más el adaptador antes de abrirlo:

- Claude Code: `.claude/skills/revisar-documento/`. Añade al frontmatter de su
  SKILL.md las dos claves de `adaptadores/claude-y-vscode-frontmatter.yaml`.
- Copilot en VS Code: `.github/skills/revisar-documento/`. Añade las mismas dos claves
  al frontmatter de su SKILL.md. Un YAML auxiliar suelto no basta.
- Codex nativo: `.agents/skills/revisar-documento/`. Copia
  `adaptadores/codex/agents/openai.yaml` a `revisar-documento/agents/openai.yaml`.

Claude/VS Code: `disable-model-invocation: true` y `user-invocable: true`.
Codex: `policy.allow_implicit_invocation: false`. Los controles son documentales;
su efecto no se ha probado aquí. No copies tres skills duplicadas al mismo cliente.

Fuentes consultadas: https://agentskills.io/specification,
https://learn.chatgpt.com/docs/build-skills,
https://code.claude.com/docs/en/skills,
https://code.visualstudio.com/docs/agent-customization/agent-skills.

## Revisión estática opcional

Requiere Python 3 y PyYAML ya disponibles. No necesitas instalarlos para comparar
los archivos manualmente. El script no llama a modelos, usa la red ni modifica
los documentos; lee el archivo indicado y sus enlaces simples. Desde esta carpeta:

```text
python audit_skill.py antes/revision-local/SKILL.md
python audit_skill.py despues/revisar-documento/SKILL.md
```

La primera orden devuelve código 1: tres reglas fallan y dos campos piden REVIEW.
La segunda devuelve código 0: pasan las cinco reglas. Código 0 no implica que la
skill haya sido descubierta, cargada o aplicada por un asistente.

Reglas: R1 mapa YAML; R2 name/description; R3 nombre ASCII y carpeta; R4 enlaces
Markdown inline simples dentro de la carpeta; R5 patrones de ruta con unidad,
`/Users/`, `/home/` o `~/`. No analiza todo Markdown/YAML, todas las rutas absolutas,
enlaces externos, dependencias, permisos o semántica de herramientas. No es el
validador oficial ni una comprobación exhaustiva de Agent Skills.

`resultados.json` registra un control positivo y seis mutaciones: YAML roto,
description ausente, nombre distinto, enlace ausente, ruta personal y campo de
cliente. La última produce REVIEW; el resto activa la regla prevista.
`manifest-sha256.json` permite comprobar integridad, no autoría ni compatibilidad.

## Prueba funcional pendiente, para quien use un cliente

Necesitas acceso habitual al cliente y permiso para leer los documentos. Copia
`caso/borrador.md` y `caso/referencia.md` a la carpeta de trabajo; guarda la pauta
`caso/resultado-referencia.md` fuera de las entradas del asistente.

Comprueba primero que tu skill aparezca y qué archivos carga. Invócala por nombre
($revisar-documento en Codex; /revisar-documento al inicio en Claude Code;
selección slash en Copilot VS Code), indicando las dos entradas y «no edites».
Contrasta el resultado con la pauta editorial: fecha 5 de noviembre, retirar la
garantía sin errores, conservar horario y cupo. Registra versión, agente, permisos,
salida y bloqueos. Si no puede leer una entrada, detén la evaluación funcional.
No cambies permisos para forzar el resultado. No tomes una autoafirmación de uso
de la skill como evidencia única de carga. Una salida correcta por sí sola también
puede proceder del prompt: la carga y la calidad se verifican por separado.

Después prueba un prompt equivalente sin invocación explícita para evaluar la
política manual, usando la evidencia de carga disponible. Un solo caso sin carga
no garantiza el control en todas las tareas. La frase «solo manual» expresa el
objetivo de configuración, no una barrera de permisos para otras herramientas.

Licencia del material propio: MIT, ver LICENSE.txt. No incluye software de los clientes.