Estructuración de Instrucciones Paso a Paso que Claude Puede Seguir de Forma Fiable
La descripción permite que una Skill sea descubierta. Las instrucciones deciden si realmente funciona.
Una vez que Claude ha emparejado una tarea con una Skill, todo a partir de ese momento depende del cuerpo del archivo SKILL.md: los pasos reales que debe seguir.
Las instrucciones sueltas, de estilo de párrafo, tienden a producir resultados inconsistentes: un enfoque ligeramente diferente cada vez, detalles manejados de forma distinta entre ejecuciones, un final que varía en forma.
Esta página trata sobre la estructura que evita eso: pasos claros y numerados que un lector (y Claude) puede seguir de la misma manera cada vez.
Resumen
- Idea Central: Las instrucciones estructuradas como pasos ordenados y concretos producen un comportamiento consistente; las instrucciones escritas como prosa invitan a la deriva.
- Por Qué Importa: Una Skill que se comporta de manera diferente cada vez que se ejecuta es difícil de confiar, incluso si cada ejecución individual parece razonable.
- Conceptos Clave: pasos numerados, pasos de acción única, verbos ambiguos, ramificación, final definido, granularidad de los pasos.
- Cuándo Usar: Utiliza esto siempre que estés redactando el cuerpo de una Skill, o cuando una Skill existente produzca resultados inconsistentes en tareas similares.
- Limitaciones / Compensaciones: Los pasos muy granulares mejoran la consistencia pero pueden hacer que las tareas simples parezcan sobre-ingenierizadas; la granularidad adecuada depende de cuánta variabilidad tenga realmente la tarea.
- Temas Relacionados: Escribir una descripción eficaz, delimitar el acceso a herramientas, agrupar archivos de referencia, errores comunes de las Skills.
Fundamentos
El cuerpo de instrucciones de un archivo SKILL.md es lo que Claude ejecuta realmente una vez que una Skill ha sido activada. Su trabajo es ser seguido de la misma manera cada vez, no solo ser leído una vez y entendido en espíritu.
La forma más fiable para eso es una lista numerada de pasos concretos.
## Instrucciones
1. Lee el diff de la pull request proporcionado por el usuario.
2. Comprueba cada archivo modificado contra la lista de verificación del equipo (nomenclatura, pruebas, comentarios).
3. Enumera cualquier elemento de la lista de verificación que falle, con el archivo y la línea específicos.
4. Si todos los elementos pasan, indícalo claramente en lugar de enumerar los fallos.
5. Muestra los resultados como un resumen corto de aprobado/fallido por cada elemento de la lista de verificación.Cada línea numerada hace una cosa. No hay un paso que diga "manejar apropiadamente" - eso es un párrafo que pretende ser un paso, y producirá un resultado diferente dependiendo del estado de ánimo, la redacción y el contexto cada vez que se ejecute.
Contrasta eso con una versión en párrafo de la misma tarea:
Revisa el diff de la PR y compruébalo con nuestra lista de verificación habitual, anotando
cualquier cosa que no parezca correcta, y hazle saber al usuario qué necesita arreglarse
antes de que pueda ser fusionado.Ambos describen la misma tarea subyacente. Solo uno de ellos le dice a Claude, sin ambigüedades, qué comprobar, en qué orden y cómo debe ser la salida.
Mecánicas e Interacciones
La estructura de pasos fiable se reduce a un pequeño número de hábitos, aplicados consistentemente.
Una acción por paso. Si un paso contiene "y" uniendo dos acciones genuinamente separadas, generalmente son dos pasos. "Leer las notas y redactar un resumen" oculta un paso completo (decidir cómo agrupar las notas) dentro de una sola línea.
Verbos concretos sobre los vagos. "Manejar el formato apropiadamente" y "revisar en busca de problemas" son frases comunes que suenan a instrucciones pero que en realidad no especifican una acción. Reemplázalas con la comprobación real: "aplicar la guía de estilo de la casa", "marcar cualquier función de más de 40 líneas".
Ramas explícitas en lugar de condiciones enterradas. Cuando una tarea realmente se bifurca basándose en la entrada, escribe la bifurcación como su propio paso con sub-rutas etiquetadas, no como una cláusula dentro de una oración más larga.
3. Comprueba la longitud de la transcripción.
3a. Si es inferior a 500 palabras, resume en un solo párrafo.
3b. Si es de 500 palabras o más, resume con un párrafo por tema discutido.Esto es más verboso que "resumir apropiadamente según la longitud", pero elimina las conjeturas que hacen que diferentes ejecuciones tracen la línea en lugares diferentes.
Un final definido. El último paso debe describir exactamente lo que se produce: su forma, no solo "concluir". "Generar los cuatro campos anteriores como un resumen estructurado corto" deja mucho menos margen para la deriva que "proporcionar tus hallazgos".
La granularidad de los pasos debe coincidir con la variabilidad real, no con el hábito. Una tarea con un camino fijo necesita pasos menos numerosos y más gruesos. Una tarea que realmente se bifurca en la variación del mundo real necesita que esa variación se explique. Añadir pasos numerados a una tarea que no tiene puntos de decisión reales solo añade ruido.
Demasiado grueso: "1. Revisa el documento y resúmelo."
Demasiado fino: "1. Abre el documento. 2. Lee la primera frase.
3. Lee la segunda frase. ..."
Tamaño correcto: "1. Lee el documento completo. 2. Identifica las tres
afirmaciones principales. 3. Resume cada afirmación en una frase.
4. Genera las tres frases como una lista numerada."Consideraciones Avanzadas y Aplicaciones
A medida que las instrucciones crecen más allá de unos pocos pasos, dos opciones estructurales adicionales empiezan a importar: la agrupación y la referencia.
Agrupar pasos relacionados bajo sub-encabezados mantiene un cuerpo de instrucciones largo escaneable, de la misma manera que un documento largo se beneficia de encabezados de sección en lugar de una lista continua.
## Instrucciones
### Recopilación de Entrada
1. Lee las notas o transcripción proporcionadas.
2. Confirma que la entrada incluye un rango de fechas; si falta, solicítalo.
### Producción del Resumen
3. Agrupa los elementos en enviados, en progreso y bloqueados.
4. Redacta de tres a cinco frases por grupo.
### Finalización
5. Genera el resumen agrupado como respuesta final.Referenciar archivos empaquetados por nombre, en lugar de incluir todo en línea, mantiene la lista de pasos principal centrada en la secuencia de acciones en lugar del detalle completo de cualquiera de ellas. Un paso como "aplicar las reglas de formato en style-guide.md" indica a Claude que cargue ese archivo solo cuando sea realmente necesario, en lugar de obligar a cada ejecución a leer material de referencia que la tarea podría no requerir.
| Enfoque | Fortaleza | Debilidad | Mejor Ajuste |
|---|---|---|---|
| Lista numerada plana | Sencillo de escribir y escanear | Se vuelve difícil de manejar más allá de ~8-10 pasos | Tareas cortas y lineales |
| Pasos agrupados bajo sub-encabezados | Se mantiene legible a medida que la tarea crece | Estructura ligeramente más compleja de mantener | Tareas de múltiples fases (recopilar, procesar, generar) |
| Pasos que referencian archivos empaquetados | Mantiene la lista principal corta; el detalle se carga solo cuando es necesario | Requiere que el archivo empaquetado exista y esté nombrado claramente | Tareas con material de referencia extenso (guías de estilo, esquemas, plantillas) |
Un hábito útil una vez que se ha redactado una lista de pasos: léela como una lista de verificación que un nuevo compañero de equipo podría seguir sin hacer una pregunta aclaratoria. Cualquier punto en el que esperarías un "espera, ¿qué significa eso?" es un paso que necesita ser más concreto, dividirse en una rama o reformularse con un verbo específico.
Las instrucciones también se benefician de la misma mentalidad de iteración que las descripciones. Ejecutar la Skill contra algunas entradas reales y variadas y comparar los resultados para detectar inconsistencias no deseadas es la forma más fiable de encontrar pasos que son en realidad más vagos de lo que parecían en papel.
Conceptos Erróneos Comunes
- "La prosa bien escrita es tan fiable como los pasos numerados." - La prosa puede estar bien escrita y aun así dejar ambigua la secuencia real de acciones, ya que el lenguaje natural no fuerza un orden explícito como lo hace una lista numerada.
- "Más pasos siempre significa más fiabilidad." - Rellenar una tarea simple y lineal con granularidad excesiva añade ruido sin añadir consistencia. La granularidad debe seguir los puntos de decisión reales de la tarea.
- "Las ramas hacen que las instrucciones sean demasiado complicadas como para valer la pena escribirlas." - Una rama no escrita no desaparece, simplemente se resuelve de forma inconsistente en tiempo de ejecución. Escribirla explícitamente es lo que elimina la inconsistencia.
- "Las instrucciones solo necesitan describir el objetivo, no el proceso." - Un objetivo claro sin un proceso claro todavía deja el camino real hacia ese objetivo subespecificado, que es exactamente lo que produce la deriva entre ejecuciones.
- "Si la Skill funciona una vez, las instrucciones están bien." - Una única ejecución exitosa no prueba la consistencia. La prueba real es si varias entradas diferentes pero similares producen resultados con la misma forma.
Preguntas Frecuentes
¿Por qué los pasos numerados producen resultados más consistentes que un párrafo?
Una lista numerada fuerza un orden explícito y una acción discreta por paso, eliminando la ambigüedad que deja un párrafo sobre qué sucede primero, qué sucede después y dónde termina realmente la tarea.
¿Cómo sé si un paso es demasiado vago?
- Si utiliza una frase como "manejar apropiadamente", "revisar en busca de problemas" o "concluir", está describiendo un resultado en lugar de una acción.
- La solución es reemplazarlo con la comprobación o acción específica que esa frase estaba representando.
¿Debería dividirse cada "y" en un paso en dos pasos?
- No siempre, pero si las dos mitades son acciones genuinamente separadas en lugar de una acción continua, dividirlas en sus propios pasos generalmente mejora la fiabilidad.
¿Cómo debo escribir una rama en las instrucciones?
Escribe la bifurcación como su propio paso con sub-rutas etiquetadas (como 3a y 3b), indicando la condición exacta que decide qué ruta se aplica, en lugar de incluir la condición en una sola oración densa.
¿Qué debe hacer el último paso de una lista?
- Describe exactamente lo que se produce y en qué forma, para que no haya ambigüedad sobre cuándo se completa la tarea.
¿Hay un número ideal de pasos para las instrucciones de una Skill?
No hay un número fijo: el recuento correcto coincide con la complejidad real de la tarea. Una tarea lineal simple podría necesitar cuatro o cinco pasos; una tarea multifase podría necesitar más, idealmente agrupados bajo sub-encabezados.
¿Cuándo deben agruparse los pasos bajo sub-encabezados en lugar de dejarlos como una lista plana?
- Una vez que una lista de pasos crece más allá de aproximadamente ocho a diez elementos, o la tarea tiene naturalmente fases distintas (recopilación de entrada, procesamiento, generación de salida), agrupar bajo sub-encabezados la mantiene escaneable.
¿Cómo pruebo si mis instrucciones son fiables?
Ejecuta la Skill contra algunas entradas reales y variadas y compara los resultados. Las diferencias no deseadas en forma o enfoque entre ejecuciones apuntan a un paso que es más vago de lo que parecía al escribirlo.
¿Deben las instrucciones referenciar directamente los archivos empaquetados o repetir su contenido en línea?
- Referenciar un archivo empaquetado por nombre (como una guía de estilo o un esquema) mantiene la lista de pasos principal enfocada y permite a Claude cargar el detalle solo cuando un paso lo requiere realmente.
¿Cuál es la diferencia entre una instrucción bien estructurada y una lista de verificación que un compañero de equipo podría seguir?
Idealmente no hay ninguna: una buena prueba para la calidad de las instrucciones es si un nuevo compañero de equipo podría ejecutar los pasos sin necesidad de hacer una pregunta aclaratoria sobre lo que significa un paso determinado.
¿Añadir más detalle a cada paso siempre mejora la fiabilidad?
- No. El detalle debe seguir la variabilidad real de la tarea. Añadir detalle exhaustivo a un paso que no tiene un punto de decisión real solo alarga las instrucciones sin hacer que la salida sea más consistente.
Relacionados
- Fundamentos de Diseño y Empaquetado de Skills - un primer ejemplo de trabajo de una lista corta de pasos.
- Escribir una Descripción de Skill Eficaz que Claude Activará - lo que tiene que tener éxito antes de que se lean estos pasos.
- Tutorial: Empaquetar Archivos y Scripts de Referencia en un Paquete de Skill - cómo referenciar detalles desde dentro de un paso.
- Delimitar el Acceso a Herramientas de una Skill con allowed-tools - restringir lo que un paso tiene permitido hacer.
- Anatomía de un Archivo SKILL.md - dónde se encuentra el cuerpo de instrucciones dentro del archivo completo.
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.