scaffold-exercises

Visión general de la skill scaffold-exercises

La skill scaffold-exercises ayuda a un agente a crear estructuras de carpetas de ejercicios que respetan una convención estricta de contenido formativo: secciones numeradas, ejercicios numerados, subcarpetas por variante como problem/, solution/ y explainer/, además de archivos mínimos con la validez suficiente para superar comprobaciones orientadas a lint. Si estás creando material de curso, ejercicios para workshops o un repositorio de aprendizaje estructurado, ese es exactamente el problema real que resuelve scaffold-exercises.

Para qué sirve mejor scaffold-exercises

Usa scaffold-exercises cuando ya tienes claro el plan de aprendizaje y necesitas que el armazón del sistema de archivos se cree de forma correcta, rápida y consistente. Encaja especialmente bien para:

• preparar una nueva sección de curso dentro de exercises/
• crear varios esqueletos de ejercicios a partir de un temario
• añadir variantes problem, solution o explainer sin tener que adivinar las reglas de nomenclatura
• evitar directorios iniciales mal formados que luego fallen en el lint del repo

Quién debería instalar scaffold-exercises

El perfil ideal es alguien que trabaja en un repo que ya sigue una estructura docente basada en ejercicios. La scaffold-exercises skill resulta especialmente útil para maintainers, autores de temarios y editores de repos asistidos por IA que necesitan rutas correctas y archivos placeholder válidos más que generación de texto explicativo.

Qué diferencia a scaffold-exercises de un prompt genérico

Un prompt normal puede decirle a una IA “crea algunas carpetas de ejercicios”, pero scaffold-exercises añade disciplina específica del repositorio:

• las carpetas de sección usan XX-section-name
• las carpetas de ejercicio usan XX.YY-exercise-name
• los nombres van en dash-case
• cada ejercicio necesita al menos una carpeta de variante
• cada variante necesita un readme.md no vacío
• archivos de código como main.ts solo hacen falta cuando realmente existe código

Eso se traduce en menos rutas mal formadas, menos placeholders vacíos y menos trabajo de limpieza después de la generación.

La principal pregunta de adopción que conviene responder primero

Instala scaffold-exercises si tu mayor riesgo es que la estructura se desvíe de la convención, no la falta de originalidad del contenido. Esta skill está pensada para generar scaffolding que cumpla convenciones. No es, por sí sola, un planificador curricular completo, ni un redactor de lecciones, ni un generador de código.

Cómo usar la skill scaffold-exercises

Cómo suele funcionar la instalación de scaffold-exercises

El fragmento del repositorio no publica un instalador propio dentro de SKILL.md, así que el uso depende del runtime de skills que tengas. En configuraciones basadas en Skills, lo habitual es añadir el repo fuente y luego invocar la skill scaffold-exercises por nombre. Si tu entorno lo admite, un patrón común es:

npx skills add mattpocock/skills --skill scaffold-exercises

Si tu plataforma de agentes carga las skills de otra forma, apúntala al repositorio mattpocock/skills y selecciona scaffold-exercises.

Lee primero este archivo antes de usar scaffold-exercises

Empieza por:

• scaffold-exercises/SKILL.md

Esta skill es simple y autocontenida. En la vista previa del repositorio no aparecen rules/, resources/ ni scripts auxiliares adicionales, así que la mayor parte del comportamiento útil está codificada directamente en ese único archivo.

Qué información necesita scaffold-exercises por tu parte

La skill funciona mejor cuando le das un plan con estas cuatro piezas:

1. el número y el título de la sección
2. los números y títulos de los ejercicios
3. qué variantes debe incluir cada ejercicio
4. si quieres solo stubs o código inicial real

Sin eso, el agente todavía puede generar el scaffold, pero tomará decisiones por defecto que quizá no te interesen, sobre todo en lo relativo a explainer/ frente a problem/.

El prompt mínimo que funciona

Un prompt básico pero funcional de scaffold-exercises usage sería así:

Use scaffold-exercises to create section 03-search-fundamentals under exercises/. Add exercises 03.01-tokenization-basics and 03.02-bm25-ranking. Each should have problem/ and solution/ folders with non-empty readme.md files. Stub only, no code yet.

Esto basta porque aporta numeración, nombres, ubicación y tipos de variante.

Un prompt mejor que mejora la calidad de salida

Un prompt mejor deja claros los valores por defecto:

Use scaffold-exercises for Skill Scaffolding in this repo. Create exercises/03-search-fundamentals/. Add:

• 03.01-tokenization-basics with explainer/
• 03.02-bm25-ranking with problem/ and solution/
• 03.03-query-expansion with problem/

For each variant, create a non-empty readme.md with the final exercise title and a one-sentence description. Do not add main.ts unless the variant includes code. Keep all names dash-case.

Por qué funciona mejor:

• elimina la ambigüedad sobre las variantes de carpeta
• evita archivos de código innecesarios
• preserva las convenciones de nombres desde el inicio
• le dice al agente qué significa en la práctica que algo sea “non-empty”

Comportamiento por defecto que debes esperar si el plan está incompleto

Uno de los detalles más importantes de la skill upstream: al crear stubs, el valor por defecto es explainer/ salvo que el plan diga otra cosa. Eso viene bien para ejercicios conceptuales, pero puede ser incorrecto si en realidad necesitas espacios de trabajo para el alumnado. Si quieres tareas prácticas, indica problem/ de forma explícita.

Qué va a crear scaffold-exercises

La skill scaffold-exercises está orientada a un patrón de directorios repetible como este:

• exercises/01-section-name/
• exercises/01-section-name/01.01-exercise-name/problem/readme.md
• exercises/01-section-name/01.01-exercise-name/solution/readme.md

Para scaffolds de tipo stub, se aceptan carpetas con solo readme.md. Si más adelante añades código, entonces main.ts debería existir y contener algo más que un placeholder trivial de una sola línea.

Flujo de trabajo práctico para usar scaffold-exercises en un repo real

Un buen flujo de trabajo es:

1. Redacta el esquema del temario en lenguaje natural.
2. Convierte ese esquema en nombres numerados de secciones y ejercicios.
3. Especifica las variantes de cada ejercicio.
4. Pide al agente que ejecute scaffold-exercises.
5. Revisa los nombres de las rutas antes de añadir contenido.
6. Ejecuta el paso de lint o validación de tu repo.
7. Solo entonces completa el código y la documentación más desarrollada.

Este orden importa porque la skill rinde mejor cuando se usa primero para la estructura.

Errores de nomenclatura que generan más retrabajo

Las entradas incorrectas más habituales son:

• omitir prefijos numéricos
• usar espacios en lugar de dash-case
• confundir la numeración de secciones con la de ejercicios
• no indicar si las carpetas deben ser problem, solution o explainer

Si tu plan dice “Create an exercise on BM25”, el agente todavía tiene que inventar demasiado. Si tu plan dice “Create 01.03-retrieval-with-bm25 inside 01-retrieval-skill-building with problem/ and solution/,” el resultado suele ser fiable.

Cuándo encaja scaffold-exercises para Skill Scaffolding

scaffold-exercises for Skill Scaffolding encaja bien cuando tu cuello de botella es la forma del repo y la consistencia. Encaja mal cuando necesitas pedagogía rica, evaluaciones o explicaciones pulidas generadas automáticamente. Conviene tratarla como una herramienta que impone estructura, no como un sustituto del diseño instruccional.

Preguntas frecuentes sobre la skill scaffold-exercises

¿scaffold-exercises es apta para principiantes?

Sí, siempre que ya entiendas la estructura de ejercicios que quieres. La skill en sí es simple: sobre todo hace cumplir nombres, disposición de carpetas y archivos mínimos obligatorios. La parte más difícil suele ser decidir antes el currículo y las variantes.

Cuándo no deberías usar scaffold-exercises

Omite scaffold-exercises si:

• tu repo no usa carpetas numeradas de secciones y ejercicios
• solo necesitas una lección en markdown, no un árbol de ejercicios
• quieres que la IA invente desde cero la arquitectura del curso
• tu proyecto usa un contrato de archivos distinto de readme.md más main.ts opcional

En qué se diferencia scaffold-exercises de crear carpetas manualmente

Crear el scaffold a mano está bien para un solo ejercicio. El valor de scaffold-exercises usage aparece cuando creas muchos ejercicios y necesitas consistencia. Reduce la probabilidad de nombres inválidos, readmes vacíos y convenciones mezcladas de carpetas que rompan las comprobaciones posteriores.

¿scaffold-exercises genera el contenido completo del ejercicio?

No. Su valor principal es el scaffolding. Puede crear readmes mínimos y la estructura base, pero no deberías tratarlo como un sistema completo de autoría de lecciones.

¿Necesito siempre problem, solution y explainer?

No. Las reglas upstream solo exigen al menos uno de ellos. Para stubs, explainer/ es la opción por defecto si no se especifica otra cosa. Elige las variantes según el objetivo del ejercicio, no por costumbre.

¿scaffold-exercises está atada a una única estructura de repo?

Sí, tiene un enfoque marcado. La skill asume una jerarquía exercises/ y convenciones concretas de numeración. Si tu repo sigue ese patrón, resulta útil. Si no, acabarás invirtiendo tiempo en pelearte con sus supuestos.

Cómo mejorar la skill scaffold-exercises

Dale a scaffold-exercises un plan numerado, no una lista de temas

La forma más rápida de obtener mejores resultados con scaffold-exercises es dejar de usar prompts basados en temas y empezar a usar rutas objetivo exactas. Compara:

Débil:

• “Add some exercises about retrieval.”

Fuerte:

• “Create exercises/01-retrieval-skill-building/01.01-keyword-search, 01.02-bm25, and 01.03-hybrid-search.”

El segundo prompt apenas deja margen para que el agente nombre mal las carpetas.

Especifica la intención de cada variante en vez de dejar que decidan los valores por defecto

Si omites los tipos de variante, la skill puede elegir explainer/ para los stubs. Eso es eficiente, pero puede no encajar con tu diseño didáctico. Indica:

• usa problem/ para tareas del alumnado
• usa solution/ para referencias
• usa explainer/ para material solo conceptual

Esa única aclaración mejora de forma tangible la calidad del scaffold.

Pide readmes mínimos pero válidos

Un fallo habitual es generar placeholders que técnicamente existen, pero no resultan útiles. Pide al agente que incluya un título y una descripción de una frase en cada readme.md. Así mantienes los archivos no vacíos y facilitas el trabajo de autoría posterior.

Evita archivos de código innecesarios

Otro error frecuente es generar main.ts en todas partes. La skill upstream no lo exige para stubs basados solo en readme.md. Si quieres un scaffold ligero, indica “readme-only unless code is explicitly needed.” Así la primera pasada queda más limpia.

Valida los nombres antes de generar muchos ejercicios

Para lotes grandes, pídele al agente que primero liste las rutas propuestas y que solo las cree después de tu aprobación. Eso permite detectar colisiones de numeración y slugs poco naturales antes de que tengas que renombrar decenas de carpetas.

Itera después de la primera pasada con scaffold-exercises

Después de la primera ejecución, mejora el resultado revisando:

• continuidad de la numeración
• exhaustividad de las variantes
• utilidad de los readmes
• si cada ejercicio pertenece realmente a la sección elegida

Luego pídele al agente una segunda pasada centrada solo en correcciones. La calidad de la scaffold-exercises guide mejora de forma visible cuando se separan la generación y la revisión.

Dónde sigue siendo imprescindible el criterio humano con scaffold-exercises

La scaffold-exercises skill no puede decidir por ti la secuencia didáctica adecuada, la dificultad de los ejercicios ni la cobertura pedagógica. Los mejores resultados llegan cuando la usas para automatizar la estructura y reservas la revisión humana para la lógica curricular.