Escribe tu primera skill

Aprende la anatomía, estudia un ejemplo revisado, genera el archivo abajo.

Abstract

Una skill es un método en texto plano que tu lector entrega a un asistente de IA. Escribir una se parece más a redactar un procedimiento para un compañero nuevo y despierto que a trastear con prompts: defines las entradas, los pasos, el contrato de salida y las reglas que aguantan cuando las cosas se vuelven ambiguas. Este documento enseña la anatomía, muestra un ejemplo revisado, enumera lo que se rechaza en la revisión y termina con un editor que genera un archivo conforme a la especificación.

1.Anatomía de una skill

1. Frontmatter. name en kebab-case, igual al nombre del archivo. description cumple dos funciones en un párrafo: qué hace la skill y — sobre todo — cuándo activarla ("Use when asked to…"). Los asistentes eligen skills por este campo; una descripción vaga produce una skill que duerme para siempre. Versión, licencia y autores cierran el bloque.
2. Párrafo de identidad. Dos o tres frases tras el título, en segunda persona: en quién se convierte el asistente y en qué se niega a transigir. Es voz y estándar en un mismo aliento: "You write commit messages worthy of the permanent record."
3. Inputs. La lista numerada de lo que la skill necesita, con los obligatorios marcados y una regla para los huecos (pregunta y detente, o sigue con supuestos declarados). Pregunta una sola vez — una skill que interroga por tandas agota a quien la usa.
4. Method. Pasos numerados, cada uno decidible: una instrucción que el asistente puede seguir o verificar, con las reglas de criterio explícitas ("cuando X supere Y, haz Z"). Los pasos que dicen "sé minucioso" devuelven al azar la parte difícil.
5. Output format. El contrato: secciones, orden y longitudes donde importan. Dos ejecuciones de la misma skill deben producir la misma forma — la sección de formato es lo que hace una skill repetible en lugar de improvisada.
6. Rules. Los invariantes que sobreviven a cada caso límite: qué se rechaza, qué se etiqueta, qué se degrada y cómo. Declara cómo se comporta la skill cuando falta una capacidad — "marca N.D. con un motivo" vale más que un éxito adivinado.

2.Un ejemplo revisado, anotado

---
name: honest-status-report
description: Status reports that declare failures,
  blockers and partial results as visibly as successes.
  Use when asked for a status update, a progress report,
  or an end-of-task summary.
---✓ review — name matches filename; description states the trigger ("Use when…"): the assistant knows when to wake this skill
2. Classify each item, strictly:
   - Done & verified — completed AND checked.
   - Failed / errored — attempted, went wrong.
   - Silently skipped — planned, then untouched.✓ review — each category is decidable: two readers classify the same item the same way
The order is fixed: problems before achievements.✓ review — an output contract, stated as a rule: the shape survives every run

3.Qué se rechaza en la revisión

Cada propuesta la lee línea por línea un maintainer, después de que pasen las comprobaciones automáticas. Estos son los rechazos recurrentes — escribe con esta lista abierta:

1. REJECTED — Pasos no decidibles. "Analiza con cuidado", "sé útil", "usa tu criterio" sin criterio alguno. Un paso se gana su lugar cuando el asistente puede saber si lo ha cumplido.
2. REJECTED — Degradación ausente. El método da por hechos el acceso web, la ejecución de código o las herramientas de archivos, y calla sobre qué ocurre en un asistente que carece de ellos. Declara la alternativa.
3. REJECTED — Contenido oculto o codificado. Blobs base64, caracteres de ancho cero, instrucciones para descargar contenido remoto en tiempo de ejecución. El trato es markdown legible en claro: lo que el lector ve es lo que el agente ejecuta.
4. REJECTED — Vías de exfiltración. Pasos que envían los datos del usuario a alguna parte. Una skill transforma lo que recibe, en el sitio.
5. REJECTED — Fórmulas atadas a un proveedor. "Usa la herramienta WebFetch", "llama a Code Interpreter". Nombra capacidades ("cuando hay acceso web en vivo") y la skill funciona en cualquier asistente.
6. REJECTED — Marketing dentro del método. Superlativos sobre la propia skill, enlaces a productos, autopromoción. El método habla a través de sus pasos.
7. REJECTED — Contrato de salida ausente. Diez pasos de método afilados y ni una palabra sobre qué aspecto tiene el entregable. La sección de formato es la mitad del valor.

4.El editor — genera tu archivo

Rellena las secciones; el editor ensambla un .md conforme a la especificación. Todo se ejecuta en esta página — tu borrador no toca ningún servidor. El formulario sigue en inglés: lo que escribas se convierte en la skill, y las skills de esta biblioteca están en inglés.

5.Propónla

1. Ejecuta primero tu skill en un caso real — la salida de prueba te dice dónde el método es delgado.
2. Haz un fork de la biblioteca, añade tu archivo en skills/<category>/<name>.md y abre una pull request por skill.
3. Firma cada commit con git commit -s. Ese único flag añade la línea Signed-off-by con la que certificas que puedes publicar el trabajo bajo Apache-2.0 — el Developer Certificate of Origin. Una comprobación obligatoria lo verifica, así que la PR se incorpora en cuanto está. ¿Ya has hecho commit sin ella? git commit --amend -s --no-edit para el último, git rebase --signoff main para varios, y luego git push --force-with-lease.
4. Se ejecutan las comprobaciones automáticas, luego un maintainer lo lee línea por línea. El crédito queda en el propio archivo.