coursmith-curso

Crear y publicar un curso de Coursmith

Escribes un curso como una carpeta que contiene course.json y un directorio assets/, lo verificas con la CLI coursmith y lo envías. Un agente de revisión en el portal lo aprueba, solicita una revisión o lo rechaza. Tu trabajo termina cuando el curso es aprobado, o cuando has explicado el resultado de la revisión al usuario.

Ejecuta la CLI como npx --yes coursmith@latest <comando> --json. El paquete npm público incluye la CLI y esta habilidad; no se necesita acceso a GitHub ni instalación global. Si falta npx, pide al usuario que instale Node.js 20 o superior y siga la guía en /install. Con --json, cada comando imprime un documento JSON; léelo en lugar de adivinar.

Archivos de referencia en esta carpeta de habilidad (léelos cuando llegues al paso correspondiente):

Archivo	Úsalo para
references/course.schema.json	La estructura exacta de course.json. Las claves desconocidas son rechazadas.
references/block-catalog.md	Cada bloque de contenido y visual, con ejemplos JSON válidos y reglas.
references/animation-presets.md	Los 7 presets de animación y cuándo usar cada uno.
references/writing-guide.md	Cómo escribir pasos, glosarios y cuestionarios que pasen la revisión.
references/content-policy.md	Lo que no está permitido y cómo tratar temas sensibles.
examples/sample-course/	Un curso completo que pasa la validación. Copia su estructura.

1. Iniciar sesión

1. Ejecuta npx --yes coursmith@latest whoami --json. Si imprime un username, continúa al paso 2.
2. De lo contrario, ejecuta npx --yes coursmith@latest login --no-wait --json. Muestra al usuario la verificationUri y el userCode y pídele que abra el enlace, verifique el código y haga clic en Aprobar.
3. Cuando el usuario confirme, ejecuta npx --yes coursmith@latest login --resume --json y verifica que imprime logged_in.

2. Acordar el curso con el usuario

Pregunta, en un solo mensaje, cualquier cosa que el usuario no haya proporcionado ya:

• Tema y, si es útil, el enfoque o la audiencia.
• Idioma del curso (cualquier idioma; necesitarás su código BCP-47 como it, en, pt-BR).
• Dificultad: beginner, intermediate o advanced.
• Opcional: duración deseada (por defecto unos 30 minutos), requisitos previos, cosas a incluir o evitar.

Verifica el tema contra references/content-policy.md. Si no está permitido, díselo y detente. Si es un tema sensible (salud, derecho, finanzas, política, religión…), planifica un tratamiento neutral y un descargo de responsabilidad.

3. Proponer un esquema y obtener aprobación

Muestra al usuario:

• título, subtítulo de una línea, 2–6 objetivos de aprendizaje;
• 3–6 secciones, cada una con un resumen de una línea y 2–5 títulos de pasos;
• para cada paso, el visual que planeas (gráfico, diagrama, preset de animación, imagen o ninguno);
• la cantidad planificada de preguntas del cuestionario (al menos 10, que cubran cada sección).

Revisa hasta que el usuario esté de acuerdo. No escribas course.json antes de eso.

4. Escribir el curso

Crea una nueva carpeta con el nombre del curso (kebab-case) que contenga course.json y assets/. Sigue exactamente references/course.schema.json y copia la estructura de examples/sample-course/course.json.

Reglas que el validador aplica (detalles en references/block-catalog.md):

• schemaVersion es "1.0". No escribas courseId: la CLI lo gestiona.
• Todos los ids son letras minúsculas, dígitos y guiones, únicos en todo el curso (secciones, pasos, activos, preguntas del cuestionario).
• Cada paso tiene un title y al menos un bloque; la mayoría de los pasos también tienen un visual.
• Glosario: cada sección tiene un glosario que define cada concepto que introduce y cada término técnico o de dominio que usa. En el texto, marca cada término como [[término]], o [[término|texto mostrado]] cuando la redacción sea diferente (usa aliases para plurales e inflexiones). Un término marcado debe estar definido en la misma sección o en una anterior. Las definiciones son autocontenidas y están escritas en el idioma del curso.
• Visuales: los gráficos son especificaciones Vega-Lite con data.values en línea (sin URLs); los diagramas son Mermaid sin click ni %%{init}%%; las animaciones usan uno de los 7 presets; las imágenes se refieren a un activo por id.
• Markdown: sin HTML sin procesar, sin imágenes Markdown (usa un bloque de imagen), los enlaces deben ser https://.
• Cuestionario final: al menos 10 preguntas; cada sección es evaluada por al menos una pregunta (sectionRef); cada pregunta tiene una explicación. Tipos: single, multiple, true_false, ordering (los elementos de ordenamiento se listan en el orden correcto; el portal los mezcla).
• Preguntas check opcionales al final de un paso dan retroalimentación rápida a los estudiantes y no se puntúan.

Escribe sección por sección y mantén el idioma, la dificultad y la terminología consistentes en todo el curso (consulta references/writing-guide.md).

5. Crear los activos

• Se requiere una imagen de portada (meta.coverImage), idealmente 1200×630.
• Si tienes una herramienta de generación de imágenes, produce archivos PNG, JPEG o WebP. De lo contrario, escribe SVG limpio a mano: formas simples, una paleta clara, viewBox configurado, sin scripts, sin enlaces externos ni fuentes, sin imágenes incrustadas.
• Para una animación highlight-svg, asigna a los elementos a resaltar un atributo id.
• Coloca cada archivo directamente en assets/ y decláralo en assets[] con kind (image o svg), file (assets/<nombre>) y un texto alt significativo. Completa generatedBy para imágenes generadas por IA.
• Cada archivo debe tener menos de 3 MB; todo el paquete menos de 25 MB.

6. Validar hasta que esté limpio

Ejecuta npx --yes coursmith@latest validate <carpeta> --json. Imprime { "ok": ..., "issues": [...] }; cada problema tiene severity, code, path (por ejemplo sections[1].steps[0].blocks[2]) y message.

Corrige cada error, luego ejecútalo de nuevo. Repite hasta que ok sea true. Corrige también las advertencias cuando sean económicas (por ejemplo glossary.unreferenced: marca el término con [[...]] donde se usa).

7. Enviar y seguir la revisión

1. Ejecuta npx --yes coursmith@latest submit <carpeta> --json. Sube el curso e imprime status: "in_review" con un submissionId. La CLI escribe .coursmith.json en la carpeta; consérvalo, ya que vincula envíos posteriores al mismo curso.
2. Ejecuta npx --yes coursmith@latest status --dir <carpeta> --wait --json (espera hasta 10 minutos; ejecútalo de nuevo si el estado sigue siendo in_review).
3. Actúa según el status:
   • approved: proporciona al usuario la courseUrl. Menciona cualquier sugerencia opcional en review.issues.
   • needs_revision: para cada problema en review.issues, abre el elemento en path, aplica la suggestion (o corrige lo que describe message), luego valida y envía de nuevo. Informa al usuario de lo que cambiaste. Los problemas con severity: "warning" son opcionales.
   • rejected: explica review.summary al usuario. No reenvíes el mismo contenido.

Si submit informa review_in_progress, espera a que termine la revisión actual con status --wait primero.

Actualizar un curso publicado

Edita la misma carpeta (conserva .coursmith.json) y envía de nuevo. La nueva versión pasa por revisión mientras la actual permanece en línea; mantén estables los ids de los pasos para que los estudiantes conserven su progreso.

Solución de problemas

Salida de la CLI	Qué hacer
not_logged_in / código de salida 3	Vuelve al paso 1.
client_outdated	Reintenta con npx --yes coursmith@latest para que npm obtenga la CLI más reciente.
validation_failed de submit	Ejecuta validate y corrige los problemas que enumera.
rate_limited	El usuario alcanzó el límite diario de envíos; inténtalo de nuevo mañana.
assets.content_type / assets.invalid	El contenido del archivo no coincide con su extensión, o está corrupto. Vuelve a exportarlo.
animation.unknown_element	El SVG carece de un elemento con ese id (los ids se conservan, los scripts y enlaces externos se eliminan).