Escribir buenas instrucciones: alcance y calibración

En el capítulo 3 vimos que la especificación es tajante sobre el cuerpo Markdown de un SKILL.md: “There are no format restrictions. Write whatever helps agents perform the task effectively”. La spec no te obliga a nada ahí dentro, y toda la dificultad real de escribir un skill vive exactamente en ese territorio sin reglas duras.

Este capítulo traduce y razona la guía oficial de buenas prácticas (skill-creation/best-practices), que es guía de autoría, no norma: ningún cliente rechazará un skill por incumplirla. Lo que sí ocurre es que un skill mal calibrado se activa cuando no debe, satura el contexto o empuja al agente por caminos improductivos. Las afirmaciones normativas (DEBE / DEBERÍA / PUEDE, traducción de los must / should / may que la especificación escribe en minúscula, sin declarar adherencia a RFC 2119) salen de specification.md y se cubrieron en el capítulo 3; todo lo de aquí son recomendaciones, y lo señalo cuando importa.

La regla de oro

Escribe para un colega competente que acaba de llegar a tu proyecto: sabe programar, pero no conoce nada de tu contexto.

El agente ya sabe qué es un PDF, cómo funciona HTTP y qué hace una migración. Lo que no sabe es que tu tabla users usa borrado lógico, que tu API llama accountId a lo que la base de datos llama user_id, o que en tu equipo las migraciones se ejecutan siempre con --backup. La guía lo formula como principio de gasto de contexto: “Add what the agent lacks, omit what it knows”.

Y ofrece un test de corte de una sola pregunta, aplicable a cada párrafo: “Would the agent get this wrong without this instruction?” (¿el agente se equivocaría sin esta instrucción?). Si la respuesta es no, corta. El corolario incómodo: si el agente ya resuelve bien la tarea completa sin el skill, puede que el skill no aporte valor. Eso se mide, no se intuye (capítulo 9).

flowchart TD
    A["Párrafo candidato<br/>para el SKILL.md"] --> B{"¿El agente lo haría mal<br/>sin esta instrucción?"}
    B -->|No| C["Cortar"]
    B -->|No estoy seguro| D["Medir con un eval<br/>capítulo 9"]
    B -->|Sí| E{"¿Se necesita en<br/>cada ejecución?"}
    E -->|Sí| F["Queda en SKILL.md"]
    E -->|Solo a veces| G["Va a references/ o assets/<br/>con condición de carga explícita"]

Parte 1: de dónde sale el contenido

El antipatrón de origen

La guía abre señalando el error más común, y es un error de procedencia, no de redacción: pedirle a un LLM que genere un skill sin darle contexto del dominio, apoyándose solo en su conocimiento general. El resultado, textual, son “vague, generic procedures (‘handle errors appropriately,’ ‘follow best practices for authentication’)”. Ese texto no falla por estar mal escrito: falla porque no contiene información que el agente no tuviera ya.

Extraer de una tarea real

El método recomendado es hacer primero la tarea de verdad, conversando con el agente, y después extraer el patrón reutilizable. Durante esa sesión hay que atender a cuatro cosas, nombradas literalmente por la guía:

Qué observar	Original	Por qué es material de skill
Los pasos que funcionaron	Steps that worked	Es la secuencia que quieres repetir
Las correcciones que hiciste	Corrections you made	Cada corrección es un error que el agente repetirá
Los formatos de entrada y salida	Input/output formats	El agente no puede adivinar el esquema de tus datos
El contexto que aportaste	Context you provided	Convenciones del proyecto que no están en ningún modelo

La fila más valiosa es la segunda: cada vez que escribiste “no, usa la librería X en vez de la Y”, produjiste una línea de skill.

Sintetizar a partir de artefactos existentes

Si ya hay conocimiento escrito en el proyecto, se puede volcar en un LLM para que sintetice el skill. La clave es que el material sea específico del proyecto. Las cinco fuentes que enumera la guía: documentación interna, runbooks y guías de estilo; especificaciones de API, esquemas y archivos de configuración; comentarios de code review e issue trackers; historial de control de versiones, sobre todo parches y correcciones; y casos de fallo reales con su resolución. Un skill de pipelines de datos sintetizado de los informes de incidentes reales de tu equipo rendirá mejor que uno sacado de un artículo genérico, porque captura tus esquemas, tus modos de fallo y tus procedimientos.

Refinar con ejecución real

Un primer borrador casi nunca es la versión buena. El ciclo recomendado es ejecutar el skill contra tareas reales y realimentar todos los resultados, no solo los fallos, con tres preguntas: qué disparó falsos positivos, qué se pasó por alto y qué se puede recortar. La inversión rinde pronto: “Even a single pass of execute-then-revise noticeably improves quality”. Y hay que leer las trazas de ejecución, no solo la salida final: si el agente pierde tiempo, las tres causas habituales que nombra la guía tienen cada una su remedio.

Causa (literal)	Síntoma en la traza	Remedio
Instrucciones demasiado vagas	Prueba varios enfoques hasta dar con uno	Ser prescriptivo en esa parte concreta
Instrucciones que no aplican a la tarea actual	Las sigue igualmente	Mover a references/ con condición de carga
Demasiadas opciones sin un default claro	Delibera sobre herramientas	Elegir un default y mencionar alternativas

Parte 2: acotar el alcance

Unidades coherentes

La analogía de la guía conviene memorizarla: “Deciding what a skill should cover is like deciding what a function should do” (decidir qué debe cubrir un skill es como decidir qué debe hacer una función). De ahí salen dos fallos simétricos:

• Demasiado estrecho: obliga a cargar varios skills para una sola tarea, con sobrecoste y riesgo de instrucciones que se contradigan entre sí.
• Demasiado amplio: se vuelve difícil de activar con precisión, porque la description tiene que abarcar tantos casos que deja de discriminar.

El ejemplo canónico: un skill que consulta una base de datos y formatea los resultados puede ser una unidad coherente; si además cubre la administración de la base de datos, “is probably trying to do too much”.

flowchart LR
    A["sql-select + sql-join + formatear-tabla<br/>Demasiado estrecho"] --> A2["3 skills cargados por tarea<br/>sobrecoste e instrucciones en conflicto"]
    B["consultar-base-de-datos<br/>consultar + formatear<br/>Unidad coherente"] --> B2["Se activa con precisión<br/>compone bien con otros skills"]
    C["base-de-datos: consultar, formatear,<br/>migrar, administrar usuarios, backups<br/>Demasiado amplio"] --> C2["description difusa<br/>dispara cuando no toca"]

La prueba práctica para decidir si dividir

No hay umbral oficial de líneas ni de temas. Estas señales, derivadas de la guía, son las que funcionan:

Señales de que hay que dividir: la description necesita la palabra “y” para unir dominios que no comparten vocabulario (“consulta bases de datos y gestiona certificados TLS”); hay secciones del cuerpo que nunca se usan juntas en la misma ejecución; las trazas muestran que el agente lee instrucciones que no aplican y las sigue igualmente; distintas partes requieren compatibility distinta (una necesita docker, otra no necesita nada).

Señales de que NO hay que dividir: las partes comparten los mismos gotchas y el mismo vocabulario de dominio; separarlas obligaría a que ambos skills se activen siempre a la vez; la única razón para dividir es que el archivo “se ve largo”.

Esa última distinción se confunde a menudo:

Problema	Solución
El skill abarca dominios distintos	Dividir en varios skills
El skill abarca un dominio, pero con mucho detalle	Mover a references/ (divulgación progresiva)

Parte 3: calibrar el nivel de detalle

Detalle moderado, no exhaustivo

Contra la intuición de que “más documentación es mejor”, la guía advierte que los skills excesivamente exhaustivos pueden hacer más daño que bien: al agente le cuesta extraer lo relevante y puede perseguir caminos improductivos disparados por instrucciones que no aplican. La frase clave: “Concise, stepwise guidance with a working example tends to outperform exhaustive documentation”. La receta es una tríada: pasos numerados + un ejemplo que funcione + los gotchas. Cuando te encuentres cubriendo cada caso límite imaginable, pregúntate si la mayoría no estarían mejor resueltos por el propio criterio del agente.

Qué dar por sabido y qué explicitar

Este es el contraste íntegro de la guía:

<!-- Demasiado verboso: el agente ya sabe qué es un PDF -->
## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. pdfplumber is recommended because it handles most cases well.

<!-- Mejor: va directo a lo que el agente no sabría por su cuenta -->
## Extract PDF text

Use pdfplumber for text extraction. For scanned documents, fall back to
pdf2image with pytesseract.

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

Cuatro categorías que sí merecen tokens: convenciones específicas del proyecto, procedimientos específicos del dominio, casos límite no obvios, y las herramientas o APIs concretas que hay que usar.

Divulgación progresiva: la condición de carga

La spec recomienda (no exige) mantener el SKILL.md por debajo de 500 líneas y de 5.000 tokens. Cuando un skill legítimamente necesita más contenido, ese material se mueve a references/ o similares. Pero mover archivos no basta: la parte que decide si funciona es decirle al agente cuándo cargar cada archivo.

Malo	Bueno
See references/ for details.	Read references/api-errors.md if the API returns a non-200 status code.

La diferencia es la palabra “if”. Sin una condición observable, el archivo o no se lee nunca o se lee siempre, y en ambos casos la divulgación progresiva deja de aportar. El tratamiento completo está en el capítulo 8.

Parte 4: calibrar el control

El principio central tiene nombre propio en la guía: match specificity to fragility (ajusta la especificidad a la fragilidad).

Dar libertad cuando hay varios caminos válidos

Cuando varios enfoques son válidos y la tarea tolera variación, conviene dar libertad. Y aquí aparece un matiz valioso: “explaining why can be more effective than rigid directives — an agent that understands the purpose behind an instruction makes better context-dependent decisions”. Un skill de code review describe qué buscar, sin prescribir los pasos exactos:

## Code review process

1. Check all database queries for SQL injection (use parameterized queries)
2. Verify authentication checks on every endpoint
3. Look for race conditions in concurrent code paths
4. Confirm error messages don't leak internal details

Ser prescriptivo cuando la operación es frágil

Cuando la operación es frágil, la consistencia importa o hay una secuencia obligada, se invierte el criterio:

## Database migration

Run exactly this sequence:

```bash
python scripts/migrate.py --verify --backup
```

Do not modify the command or add additional flags.

Y la frase que evita el falso dilema: “Most skills have a mix. Calibrate each part independently” (la mayoría de los skills tienen una mezcla; calibra cada parte por separado). La pregunta que decide el registro de cada sección es qué pasa si el agente lo hace a su manera: si no pasa nada grave, instrucción flexible con el porqué; si rompe algo o la consistencia importa, secuencia exacta.

Defaults, no menús

Cuando varias herramientas podrían servir, elige una por defecto y menciona las alternativas de pasada, en vez de presentarlas como opciones equivalentes.

Malo	Bueno
You can use pypdf, pdfplumber, PyMuPDF, or pdf2image...	Use pdfplumber for text extraction. For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.

Un menú de cuatro opciones sin criterio de elección obliga al agente a decidir con menos información que la que tenías tú al escribir el skill.

Procedimientos, no declaraciones

Un skill debe enseñar cómo abordar una clase de problemas, no qué producir en una instancia concreta:

<!-- Respuesta específica: solo sirve para esta tarea exacta -->
Join the `orders` table to `customers` on `customer_id`, filter where
`region = 'EMEA'`, and sum the `amount` column.

<!-- Método reutilizable: sirve para cualquier consulta analítica -->
1. Read the schema from `references/schema.yaml` to find relevant tables
2. Join tables using the `_id` foreign key convention
3. Apply any filters from the user's request as WHERE clauses
4. Aggregate numeric columns as needed and format as a markdown table

Esto no impide contener detalles específicos: la guía nombra tres excepciones válidas —plantillas de formato de salida, restricciones duras (“never output PII”) e instrucciones específicas de una herramienta. Lo que debe generalizar es el enfoque.

Parte 5: estructura del cuerpo

La especificación recomienda tres secciones —solo recomendaciones, no requisitos: instrucciones paso a paso (Step-by-step instructions), ejemplos de entradas y salidas (Examples of inputs and outputs) y casos límite comunes (Common edge cases). Sobre esa base, un esqueleto que funciona bien —propuesta de este curso, no de la spec— es el siguiente:

---
name: mi-skill
description: Qué hace y cuándo usarlo, con palabras clave concretas.
---

# Mi skill

Una o dos frases: qué resuelve y cuál es el resultado esperado.

## Cuándo usar esto
Condiciones observables de aplicación, y también cuándo NO aplica.

## Procedimiento
1. Paso con un comando o acción concreta
2. Paso con su verificación
3. Paso final

## Ejemplo
Entrada real y salida esperada.

## Gotchas
Hechos del entorno que contradicen las suposiciones razonables.

## Referencias
- `references/detalle.md` — leer si <condición observable>
- `scripts/validar.sh` — ejecutar antes de dar por terminado

Dos observaciones sobre el orden:

1. Los gotchas van en SKILL.md, no en un archivo referenciado: “for non-obvious issues, the agent may not recognize the trigger”. Si el agente no sabe que existe una trampa, tampoco sabrá que debe abrir el archivo que la explica.
2. Las condiciones de carga van junto a cada referencia, no en una lista suelta al final sin criterio.

Parte 6: seis patrones reutilizables

La guía nombra seis técnicas. No todo skill necesita las seis.

1. Sección de gotchas

Es el contenido de mayor valor en muchos skills: hechos específicos del entorno que contradicen las suposiciones razonables. No son consejos generales, son correcciones concretas a errores que el agente cometerá si nadie se lo dice:

## Gotchas

- The `users` table uses soft deletes. Queries must include
  `WHERE deleted_at IS NULL` or results will include deactivated accounts.
- The user ID is `user_id` in the database, `uid` in the auth service,
  and `accountId` in the billing API. All three refer to the same value.
- The `/health` endpoint returns 200 as long as the web server is running,
  even if the database connection is down. Use `/ready` to check full
  service health.

El consejo operativo que acompaña a este patrón es el bucle de mejora más barato que existe: cada vez que corriges al agente, esa corrección se convierte en una línea de gotchas.

2. Plantillas para el formato de salida

Cuando necesitas una salida con formato concreto, dar una plantilla es más fiable que describirlo en prosa, “because agents pattern-match well against concrete structures”. Regla de ubicación: plantillas cortas, en línea en el SKILL.md; plantillas largas o que solo hacen falta en ciertos casos, en assets/, referenciadas desde SKILL.md para que se carguen solo cuando se necesiten.

## Report structure

Use this template, adapting sections as needed:

```markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
```

3. Listas de verificación para flujos de varios pasos

Una checklist explícita ayuda al agente a llevar la cuenta y a no saltarse pasos, sobre todo cuando hay dependencias o puertas de validación entre ellos:

## Form processing workflow

Progress:
- [ ] Step 1: Analyze the form (run `scripts/analyze_form.py`)
- [ ] Step 2: Create field mapping (edit `fields.json`)
- [ ] Step 3: Validate mapping (run `scripts/validate_fields.py`)
- [ ] Step 4: Fill the form (run `scripts/fill_form.py`)

4. Bucles de validación

El patrón es: hacer el trabajo, ejecutar un validador, corregir lo que falle, repetir hasta que pase.

## Editing workflow

1. Make your edits
2. Run validation: `python scripts/validate.py output/`
3. If validation fails: review the error, fix the issues, run validation again
4. Only proceed when validation passes

El validador no tiene por qué ser un script: un documento de referencia sirve, si le indicas al agente que contraste su trabajo contra él antes de terminar.

5. Plan-validar-ejecutar

Para operaciones por lotes o destructivas, la secuencia segura es que el agente produzca un plan intermedio en formato estructurado, lo valide contra una fuente de verdad y solo entonces ejecute:

## PDF form filling

1. Extract form fields: `python scripts/analyze_form.py input.pdf` → `form_fields.json`
2. Create `field_values.json` mapping each field name to its intended value
3. Validate: `python scripts/validate_fields.py form_fields.json field_values.json`
4. If validation fails, revise `field_values.json` and re-validate
5. Fill the form: `python scripts/fill_form.py input.pdf field_values.json output.pdf`

La guía marca cuál es la pieza imprescindible: “The key ingredient is step 3: a validation script that checks the plan against the source of truth”. Y el detalle que cierra el bucle solo: el mensaje de error debe bastar para autocorregirse. El ejemplo oficial dice qué campo no existe y además lista los campos disponibles, con lo que el agente corrige sin volver a preguntar.

6. Empaquetar scripts reutilizables

Al comparar trazas de ejecución entre casos de prueba, si el agente reinventa la misma lógica en cada corrida —construir gráficos, parsear un formato, validar la salida—, esa es la señal para escribir un script probado una sola vez y empaquetarlo en scripts/. Su diseño es el tema del capítulo 7.

Parte 7: antipatrones lado a lado

1. Explicar lo que el agente ya sabe

Malo	Bueno
Los archivos JSON son un formato de intercambio de datos basado en texto...	El endpoint devuelve JSON con la clave 'items' en snake_case, no camelCase.

2. Consejos genéricos sin contenido

Malo	Bueno
Handle errors appropriately and follow best practices for authentication.	The API returns 429 with a Retry-After header. Wait that many seconds before retrying; retrying immediately gets the key blocked for an hour.

3. Menú de opciones sin default

Malo	Bueno
For HTTP you can use requests, httpx, urllib3, or aiohttp depending on your preference.	Use httpx with follow_redirects=True. For synchronous scripts where httpx is not installed, requests is an acceptable fallback.

4. Referencia sin condición de carga

Malo	Bueno
More information is available in the references/ directory.	Read references/api-errors.md if the API returns a non-200 status code.

5. La respuesta en vez del método

Es el antipatrón de procedures over declarations visto en la parte 4: escribir la consulta SQL concreta de este informe en lugar del método para construir cualquier consulta analítica. El síntoma es que el skill deja de servir en cuanto cambia un filtro.

6. Prescriptivo donde daba igual, flexible donde era frágil

Situación	Error frecuente	Corrección
Nombres de variables en el código generado	Imponer una convención exhaustiva de 20 líneas	Dejarlo al criterio del agente
Ejecutar una migración de base de datos	”Ejecuta la migración como te parezca”	Comando exacto, sin flags adicionales

7. Un skill que hace de todo

Malo	Bueno
Un skill backend que cubre migraciones, despliegue, monitorización y revisión de código	Cuatro skills, cada uno con su description discriminante y sus propios gotchas

8. Un SKILL.md de 2.000 líneas

La spec recomienda menos de 500 líneas y menos de 5.000 tokens para el cuerpo. Superarlo no invalida el skill —no es una restricción dura y ningún validador la comprueba—, pero significa que el agente paga ese coste cada vez que lo activa. La corrección no es comprimir la prosa: es mover material a references/ con condiciones de carga explícitas.

Checklist de revisión

• Cada párrafo pasa el test “¿el agente lo haría mal sin esto?”.
• No hay definiciones de conceptos generales que el modelo ya conoce.
• El alcance es una unidad coherente, comparable a una función bien definida.
• Hay pasos numerados y al menos un ejemplo que funciona.
• Cada elección de herramienta tiene un default, no un menú.
• Las partes frágiles son prescriptivas; las flexibles explican el porqué.
• Los gotchas están en SKILL.md, no escondidos en references/.
• Cada referencia a un archivo lleva su condición de carga.
• El cuerpo se mantiene bajo las 500 líneas recomendadas por la spec.

Antes de seguir

Este capítulo cubre lo que el agente lee una vez que ha decidido activar el skill. Falta la otra mitad, independiente y a menudo más determinante: que esa decisión ocurra en el momento correcto. Depende del campo description, tema del capítulo siguiente.

Para empaquetar skills junto con servidores MCP, el curso hermano de Agent Plugins Spec cubre el formato de distribución. Y el catálogo de Google Skills reúne más de cien skills reales que puedes leer como ejercicio de calibración.

Resumen

• El cuerpo del SKILL.md no tiene restricciones de formato en la spec; todo lo de este capítulo son guías de autoría, no requisitos.
• Regla de oro: escribe para un agente competente pero sin contexto. Añade lo que le falta, omite lo que ya sabe; si no se equivocaría sin la instrucción, córtala.
• El contenido sale de experiencia real: una tarea hecha de verdad o artefactos específicos del proyecto, nunca de la memoria general del modelo.
• Alcance: una unidad coherente, como una función. Demasiado estrecho obliga a cargar varios skills; demasiado amplio impide activar con precisión.
• Dividir se decide por dominio, no por longitud; la longitud se resuelve con references/ y condiciones de carga explícitas.
• Detalle moderado: pasos concisos con un ejemplo funcional rinden más que documentación exhaustiva.
• Calibra el control por partes: libertad y explicación del porqué donde hay varios caminos válidos; secuencia exacta donde la operación es frágil.
• Defaults, no menús; y procedimientos, no declaraciones.
• Seis patrones reutilizables: gotchas, plantillas de salida, checklists, bucles de validación, plan-validar-ejecutar y empaquetado de scripts.
• Las 500 líneas y los 5.000 tokens son recomendaciones de la spec, no límites duros validados.

Siguiente: La description: hacer que el skill dispare cuando debe