Un sistema de tutoría descrito como un paquete de archivos independientes y legibles, cada uno responsable de una única preocupación. A tutoring system described as a package of independent, human-readable files, each responsible for a single concern.
TDL (Tutor Description Language) organiza un sistema de tutoría en un paquete de YAML y Markdown, en lugar de un único prompt con documentos subidos. La idea de fondo: los componentes de un tutor tienen distintos dueños, distintos ritmos de cambio y distintos ámbitos de reutilización, así que no deben vivir en el mismo sitio. TDL (Tutor Description Language) organizes a tutoring system into a package of YAML and Markdown, instead of a single prompt with uploaded documents. The core insight: a tutor's components have different owners, different rates of change and different reuse scopes, so they should not live in the same place.
Como el resto de la familia, no tiene runtime: los archivos se componen y se colocan en la ventana de contexto del LLM, que lee la especificación y se convierte en el tutor que describe. Lo que escribes es lo que el modelo recibe —sin intermediarios opacos—. Like the rest of the family, it has no runtime: the files are composed and placed into the LLM's context window, where the model reads the specification and becomes the tutor it describes. What you write is what the model receives — with no opaque intermediary.
Una analogía teatral ayuda: el motor es el escenario y sus reglas; el modelo instruccional es la estructura dramática; la secuencia son las notas del director para una función concreta; el contenido es el guion; la rúbrica es el marco crítico; y el manifiesto es el programa de mano. A theatrical analogy helps: the engine is the stage and its rules; the instructional model is the dramatic structure; the sequence is the director's notes for a specific performance; the content is the script; the rubric is the critical framework; and the manifest is the program handed to the audience.
Punto de entrada: identifica el curso y referencia todos los demás archivos. Cambia rara vez.Entry point: identifies the course and references every other file. Rarely changes.
Comandos de sesión (/start, /help, /next…), comportamiento operativo, idioma y límites universales.Session commands (/start, /help, /next…), operational behavior, language and universal boundaries.
La estrategia pedagógica abstracta como secuencia de eventos. La capa más reutilizable.The abstract pedagogical strategy as a sequence of events. The most reusable layer.
El plan de la lección: objetivos, perfil del tutor y unidades que mapean contenido a eventos vía implements.The lesson plan: objectives, tutor profile, and units mapping content to events via implements.
El conocimiento del dominio en Markdown plano, con encabezados ## como fronteras de sección.Domain knowledge in plain Markdown, with ## headings as section boundaries.
Criterios de evaluación estructurados, con escala de cuatro niveles (0–3) que también genera feedback.Structured evaluation criteria, with a four-level scale (0–3) that also generates feedback.
El qué vive en la secuencia de aprendizaje (objetivos, unidades, orden); el cómo vive en el modelo instruccional (las fases pedagógicas). La conexión es explícita y verificable: cada secuencia declara implements y cada unidad declara mapped_events. El validador comprueba que todo evento requerido del modelo aparezca en al menos una unidad.
The what lives in the learning sequence (objectives, units, order); the how lives in the instructional model (the pedagogical phases). The connection is explicit and verifiable: each sequence declares implements and each unit declares mapped_events. The validator checks that every required model event appears in at least one unit.
En el repositorio, un mismo curso de fundamentos de IA —los mismos seis archivos de contenido, el mismo motor, las mismas rúbricas— está empaquetado con tres modelos distintos: Gagné, Constructivista y Socrático. Lo único que cambia es instructional_model.yaml. Para investigar, esto es la comparación controlada que un prompt monolítico no permite: una sola variable, todo lo demás constante.
In the repository, one fundamentals-of-AI course — the same six content files, the same engine, the same rubrics — is packaged with three different models: Gagné, Constructivist and Socratic. The only file that changes is instructional_model.yaml. For research, this is the controlled comparison a monolithic prompt cannot offer: one variable, everything else constant.
El repositorio incluye cinco modelos prefabricados —Gagné Cinco Pasos, Experiencia Constructivista, Diálogo Socrático, Micro-lección Bloom y un híbrido Gagné-Constructivista— y puedes diseñar el tuyo. The repository includes five pre-built models — Gagné Five-Step, Constructivist Experience, Socratic Dialogue, Bloom Micro-Lesson and a Gagné-Constructivist hybrid — and you can design your own.
manifest:
spec_id: "prompt-engineering-101"
spec_version: "1.0.0"
category: FlowSpec
course:
title: "Prompt Engineering 101"
engine: engine.yaml
instructional_model: instructional_model.yaml
lessons:
- id: "lesson-01"
sequence: learning_sequence_01.yaml
content: content_01.mdUn tutor puede validarse antes de llegar a un solo estudiante. El validador revisa el paquete en cuatro niveles acumulativos: A tutor can be validated before it reaches a single learner. The validator checks the package at four cumulative levels:
Algunas reglas son reconocibles para cualquier docente: P1 cada lección con objetivos; P2 todos los eventos requeridos mapeados (la única de severidad error); P4 rúbrica si hay evaluación; P5 perfil de tutor declarado; P9 el andamiaje decrece a lo largo de la lección. Some rules are recognizable to any educator: P1 every lesson has objectives; P2 all required events mapped (the only error-severity rule); P4 a rubric where there is assessment; P5 a declared tutor profile; P9 scaffolding decays across the lesson.
python tdl_validate.py my_course/ --level allMáximo control. Cualquier editor vale. Ideal para perfiles técnicos e investigadores.Maximum control. Any editor works. Ideal for technical profiles and researchers.
Recomendado. Tres skills automatizan convertir material, construir el paquete y ejecutarlo en vivo.Recommended. Three skills automate converting material, building the package and running it live.
Para quien usa claude.ai en web. Subes la spec como conocimiento y pides que siga TDL.For claude.ai web users. Upload the spec as knowledge and ask Claude to follow TDL.
tdl-content-converter transforma PDF/DOCX/PPTX en Markdown limpio con encabezados.tdl-content-converter turns PDF/DOCX/PPTX into clean Markdown with proper headings.
tdl-builder te guía con preguntas pedagógicas y genera el paquete TDL validado en ZIP.tdl-builder guides you with pedagogical questions and generates a validated TDL package as a ZIP.
tdl-runner lee el paquete y se convierte en el tutor en vivo, listo para probar o para el alumnado.tdl-runner reads the package and becomes the live tutor, ready to test or hand to students.
Editas el YAML directamente y vuelves a ejecutar. De contenido a tutor en menos de una hora.Edit the YAML directly and run again. From content to tutor in under an hour.