🧬 Anatomía de una skill

Una skill es, en la práctica, un archivo de texto con instrucciones que le das al agente para que realice una tarea siempre de la misma manera. El formato más común es un archivo llamado SKILL.md (texto simple, en Markdown). Tiene dos partes: un encabezado breve (el frontmatter) y el cuerpo, que contienen las instrucciones reales. Vamos a abrir cada parte en el tema 2.

¿Por qué esto importa tanto en esta ruta? Porque la skill es donde codifica tu manera de trabajar y devuelve eso al harness, sin tener que repetirlo en cada conversación. Matt Pocock considera que las skills son el corazón del harness moderno: funcionan en varios agentes (Claude Code, Codex y otros) y se instalan con npx skills latest add. O error común de principiante es confundir una skill con un «prompt largo que pego cada vez». No: la skill queda guarda, se puede versionar, distribuir al equipo y —el punto central de este módulo— tú puedes activarla o por la propia IA. Quién aprieta el gatillo lo cambia todo.

Toda skill tiene dos partes bien diferenciadas. La primera es el frontmatter: un pequeño bloque en la parte superior, entre --- e ---, con dos campos esenciales — name (el nombre corto) y description (una frase que dice qué hace la skill y cuando usarla). La segunda parte es el cuerpo: todo lo que viene después del encabezado, en texto libre. Ahí es donde están el paso a paso, las reglas y los ejemplos.

La diferencia práctica entre las dos es crucial y vuelve a aparecer en el resto del módulo: la el cuerpo solo se lee cuando se activa la skill; en cambio, la description del frontmatter puede quedar "a la vista" del modelo todo el tiempo, para que decida por sí solo si invoca la skill. En palabras de Pocock, "toda skill filtra su description en la ventana de contexto". Es decir: la etiqueta consume contexto incluso cuando no se usa la skill; el cuerpo, no. Guarda esto: es la semilla del módulo 3.2 ("costo de contexto de la skill"). El error común aquí es escribir una description gigante «por si acaso»: se convierte en peso muerto en el contexto. Bien description es breve y describe exactamente el disparador.

---
name: commit-conventional
description: Cria a mensagem de commit no padrao Conventional Commits
  a partir das mudancas em stage. Use quando o usuario pedir "commita",
  "faz o commit" ou "gera a mensagem de commit".
---

# Commit Conventional

Quando acionada, faca nesta ordem:

1. Rode `git diff --staged` e leia o que mudou.
2. Escolha o tipo: feat | fix | docs | refactor | test | chore.
3. Escreva o titulo: `tipo(escopo): resumo no imperativo` (ate 72 chars).
4. No corpo, explique o PORQUE da mudanca em 1-3 linhas (nao o "o que").
5. Se houver breaking change, adicione `BREAKING CHANGE:` no rodape.
6. Mostre a mensagem final e PERGUNTE antes de rodar `git commit`.

Regras:
- Nunca invente arquivos que nao estao no diff.
- Portugues, voz imperativa, sem emoji no titulo.

Ejemplo real de SKILL.md: entre los --- está el frontmatter (etiqueta); abajo, el cuerpo (el procedimiento).

El primero de los dos tipos de skill es la procedure. La regla de oro: quien lo activa eres tú. Invocas la skill a propósito —escribiendo su nombre, seleccionándola en el menú o ejecutando un comando— y hace que el modelo «se comporte de una manera» que tú defines. En palabras de Pocock, los procedimientos son skills que «hacen que el modelo se comporte de una manera» y que tú lanza. Ejemplos de su día a día: la skill grill-me (que convierte al modelo en un entrevistador), la two-PRD e a to-issues — él encadena las tres en el orden que quiere.

¿Por qué esto importa? Porque con procedures tú te quedas al volante. Tú decides qué procedimiento se incluye, cuándo se incluye y en qué secuencia. No hay sorpresas: el modelo no activa nada por su cuenta. Pocock es explícito al preferir este modo: "I know my skills, I don't want to delegate my thinking" — conozco mis skills, no quiero delegar mi pensamiento. El error común es pensar que esto es «trabajo extra». En realidad, es control: cambias un poco de automatización por previsibilidad total y además evitas que las descripciones se filtren al contexto (tema del 3.2).

El segundo tipo es la ability. Aquí la regla de oro se da vuelta: quien lo activa es el modelo. Lee la description de las skills disponibles y, cuando «cree» que una encaja con la tarea, la usa por su cuenta, sin que se lo pidas. El ejemplo que da Pocock es una skill de coding standards (patrones de código): el modelo la invoca automáticamente cuando va a escribir React, porque la descripción dice algo como «úsala al escribir componentes React». La skill entonces le recuerda al modelo reglas como «no debe usar useEffect, debería usar otra cosa».

La ventaja es la automatización: la regla adecuada entra en el momento adecuado, sin que tengas que recordar invocarla. La desventaja —y por eso Pocock insiste tanto— es que el modelo decide, y cada ability debe mantener su description a la vista para que sea «encontrable». Como vimos, eso se filtra contexto: 100 skills se convierten en 100 descripciones colgadas de la ventana. Otra escuela, la Superpowers (del proyecto Obra), adopta precisamente este modo — el modelo al mando. Pocock prefiere lo opuesto. El error común es llenar la configuración de abilities «porque es automático» y descubrir tarde que el contexto quedó contaminado y el comportamiento, impredecible.

Ahora júntalo todo. Procedure y ability no son dos cosas diferentes — son dos puntos de entrada para la misma skill. El contenido (el cuerpo) puede ser idéntico; lo que cambia es quien tiene la llave. Por eso Pocock habla de «dos tipos de skill», pero en el fondo es una decisión de diseño para cada skill: ¿dejo que el modelo la invoque (ability) o cierro esa puerta y solo la invoco yo (procedure)? El ajuste técnico que le cierra esa puerta al modelo es el disable model invocation — lo ves en detalle en el módulo 3.2.

La consecuencia práctica es grande. Toda puerta de modelo abierta tiene un costo: la description de esa skill queda en el contexto para que el modelo pueda encontrarla. Cerrar la puerta (procedure pura) elimina ese costo y te da previsibilidad. Como prefiere estar «al volante», Pocock deja cerradas la mayoría de las puertas del modelo y mantiene el conocimiento con el humano; menciona la skill engineering zoom out como una de las que le oculta al modelo. No es una regla universal: es su estilo. El error común es ni siquiera darse cuenta de que existe esta opción: la persona instala 50 skills, todas como ability, y el contexto se convierte en un mercado.

Para cerrar: la elección no es «cuál es mejor», sino «quién debe decidir esta skill". Usa ability cuando la regla es genérica, siempre deseable y barata de aplicar mal (p. ej., patrones de estilo que siempre son válidos): conviene que el modelo la detecte por sí solo. Usa procedure cuando quieres estar al volante: tareas de razonamiento, encadenamiento de etapas o cualquier cosa en la que la previsibilidad importe más que la automatización. Pocock encadena grill-me → two-PRD → to-issues como procedimientos justamente por eso. Y recuerda el costo: cada ability mantiene su description se filtra en el contexto, así que cerrar puertas (procedure) también es higiene. Usa la guía de abajo para crear o auditar una skill:

Pra cada skill, pergunte: QUEM deve apertar o gatilho?

ESCOLHA ABILITY (modelo invoca) se:
[ ] a regra vale quase sempre que o tema aparece (ex.: padroes de React)
[ ] errar o momento e barato
[ ] voce QUER automacao, nao controle fino

ESCOLHA PROCEDURE (voce invoca) se:
[ ] e raciocinio / planejamento / etapas encadeadas
[ ] previsibilidade > automacao ("quero estar no volante")
[ ] a description ocupando contexto te incomoda -> disable model invocation: true

Regra de bolso (estilo Pocock): na duvida, PROCEDURE.
"I know my skills, I don't want to delegate my thinking."