fernbrook-labs/beginner-reference-book

Crear un libro de referencia para principiantes (guía de introducción)

Crea un libro de referencia introductorio para un lenguaje de programación o framework con el mismo diseño, mismas funcionalidades y mismo enfoque que las guías de introducción de TypeScript, Rust, Angular y Go (los ejemplos están en references/examples/). El resultado son los siguientes dos archivos:

• Un archivo HTML único (Guía de introducción a <nombre>.html) que se coloca en el escritorio. Se abre con doble clic.
• Una página compartida de claude.ai (privada; el usuario la comparte desde el menú Compartir). Solo se crea cuando el entorno dispone de la herramienta Artifact (como Claude Code).

Para mantener el mismo diseño, la apariencia y las animaciones se toman directamente de los componentes de esta skill (assets/ y scripts/). No reescribas el CSS ni el JavaScript cada vez. Lo que debes escribir es el contenido del libro (manuscrito) y la forma de verificar el código según el lenguaje.

El valor principal de un libro de referencia es que el código y los resultados que muestra sean realmente correctos. Los ejemplos de código, los mensajes de error y los resultados de ejecución deben estar verificados con el compilador real o el playground oficial (no los inventes). Las descripciones de versiones y nuevas funcionalidades también deben confirmarse mediante las notas de lanzamiento oficiales.

El trabajo lleva varias horas. En cada hito, informa al usuario con 1 o 2 frases sobre lo que estás haciendo.

1. Verificar la entrada

La entrada es el texto que aparece después del nombre de la skill (a menudo se indica como ARGUMENTS: al final del cuerpo de esta skill) o el nombre del lenguaje/framework en la solicitud del usuario.

• Cuando no se escribe nada: no comiences el trabajo. Pregunta de nuevo: «¿De qué lenguaje de programación o framework quieres crear el libro de referencia?». (Usa AskUserQuestion con hasta cuatro candidatos como Python, Java, React, Vue.js. Además, ofrece «Otro» para que el usuario pueda escribir libremente).
• Cuando se escribe algo que no es un lenguaje de programación ni un framework: explica el motivo en una frase y pide que se introduzca de nuevo un lenguaje o framework. Verifica también lo reescrito y no avances hasta que sea correcto.
• Para casos dudosos, variaciones en la escritura o múltiples especificaciones, consulta references/questions.md en la sección «Cómo verificar la entrada», donde también encontrarás ejemplos de frases. Si tienes dudas, léelo.

En entornos donde AskUserQuestion no esté disponible, pregunta lo mismo en texto y detente allí.

2. Investigar antes de preguntar

Para redactar correctamente las descripciones de las opciones, verifica lo siguiente antes de preguntar (tarda unos minutos; no realices descargas grandes todavía):

1. La versión estable más reciente y su fecha de publicación: verifícala en el sitio web oficial o en las notas de lanzamiento. Se usa para la línea « <versión> compatible» del libro.
2. Si existe un playground oficial (sitio web oficial que se pueda ejecutar en el navegador): en caso afirmativo, averigua si tiene una interfaz para enviar y compilar/ejecutar desde fuera, si se puede abrir una URL con el código incrustado, o si es del tipo «enlace compartido» (que guarda el código en el servidor).
3. Si ya está instalado en el ordenador (por ejemplo, python --version). Si no lo está, el tamaño de la instalación temporal (tamaño de la descarga oficial).
4. El espacio libre en disco (en PowerShell de Windows: Get-PSDrive C; en Git Bash: df -h /c; en macOS/Linux: df -h ~).
5. Las reglas del entorno del usuario (CLAUDE.md, AGENTS.md, etc.). Por ejemplo, si hay una regla como «no tocar carpetas sincronizadas con la nube (OneDrive, etc.)», respétala desde la investigación hasta la limpieza.

Las formas de investigar y los candidatos para la verificación según el lenguaje están en references/verification.md.

3. Preguntar las opciones de selección (las mismas que en libros anteriores)

Con AskUserQuestion, pregunta lo siguiente en una sola vez. El formato de los ítems y las opciones debe ser el mismo que en los libros de referencia anteriores (consulta references/questions.md para la plantilla de texto). Coloca la opción recomendada al principio y márcala con «(recomendado)». En entornos sin AskUserQuestion (como Codex), muestra las mismas 4 preguntas y opciones como una lista numerada (incluye también un esquema de capítulos) y espera la respuesta.

1. Público objetivo: por ejemplo, «Con experiencia en JS/TS (recomendado)», «Principiante en programación». Para frameworks basados en TypeScript (Angular, NestJS, etc.), usa «Con experiencia en TypeScript (recomendado)»; para frameworks de Python (Django, etc.), «Con experiencia en Python (recomendado)». Ajusta según el objetivo.
2. Alcance: «Solo lo básico (corto, 8-9 capítulos)», «Básico + funciones de uso común (recomendado, 12-14 capítulos)», «Hasta nivel avanzado (largo, 16-18 capítulos)». Para cada uno, muestra el esquema de capítulos en preview.
3. Formato: «Misma forma que hasta ahora (recomendado)» = un archivo HTML en el escritorio + página compartida, con preguntas de repaso, copia de código, registro de capítulos leídos y búsqueda de palabras clave. Además, «Solo archivo HTML» o «Seleccionar funcionalidades». Si el entorno no puede crear páginas compartidas (no tiene herramienta Artifact), entonces «Misma forma que hasta ahora» solo será el archivo HTML. En ese caso, no muestres «Solo archivo HTML» y no menciones la página compartida en la descripción.
4. Método de verificación: basándote en los resultados de la investigación, enumera solo los métodos disponibles. Por ejemplo, «Verificar con el playground oficial», «Verificar instalándolo temporalmente», «Verificar con ya instalado». Si el espacio en disco es escaso, recomienda un método que no requiera instalar nada en el ordenador.

Dependiendo de la respuesta, puedes preguntar una vez más.

• «Seleccionar funcionalidades» → pregunta (selección múltiple) por: preguntas de repaso al final del capítulo, botón de copia de código, casilla de verificación de capítulos leídos, glosario y búsqueda de palabras clave.
• Si el playground para verificar es del tipo «enlace compartido» (como Go Playground, que guarda el código en el servidor y crea un enlace), pregunta si se debe «crear un enlace compartido» o «copiar y pegar». Los enlaces compartidos se hacen públicos externamente y no se pueden eliminar, por lo que debes obtener el consentimiento del usuario. Los playgrounds que abren una URL con el código incrustado (Rust, TypeScript) no guardan datos, por lo que no es necesario preguntar.

Todo lo seleccionado debe respetarse en el trabajo posterior. No vuelvas a preguntar lo mismo.

4. Planificar

1. Determina el esquema de capítulos (consulta references/writing-guide.md). Cada capítulo debe leerse en unos 10 minutos. Para los lenguajes, el último capítulo debe ser «Cómo leer los errores comunes». Los esquemas de los 4 libros anteriores están en references/past-books.md.
2. Escribe el spec.json (consulta references/book-spec.md para los campos y ejemplos). Incluye: nombre de la portada, versión, público objetivo, títulos de los capítulos, lenguaje del código, cómo abrir el playground y los colores de la marca.
3. Los colores de la marca: usa los colores oficiales de la marca del lenguaje o framework. scripts/make_palette.mjs genera colores claros y oscuros a partir de un solo color y verifica que el contraste sea suficiente para la legibilidad (new_book.mjs lo llama automáticamente).

5. Crear la plantilla y escribir el manuscrito

1. La carpeta de trabajo se crea dentro de la carpeta temporal de la sesión (como el scratchpad de Claude Code; si no existe, dentro de una carpeta nueva en la carpeta temporal del sistema operativo). No la crees dentro de una carpeta sincronizada con la nube (OneDrive, etc.).
2. Crea la plantilla: node <ruta_de_esta_skill>/scripts/new_book.mjs <ruta_de_la_carpeta_del_libro> --spec spec.json
   • Se generan book.json, palette.json, src/body.html y src/ja-errors.json.
   • src/body.html ya contiene la tabla de contenidos, portada, instrucciones de uso, estructura de capítulos, estructura de preguntas de repaso y estructura de apéndices. Debes reemplazar todos los <!-- TODO … --> (si quedan, la compilación mostrará «requiere corrección»).
3. Antes de escribir, lee los ejemplos. En references/examples/ hay manuscritos extraídos de los 4 libros anteriores (portada, instrucciones de uso, un capítulo representativo, el capítulo de errores y los apéndices). Todos han sido compilados y verificados con los componentes de esta skill. En la tabla de references/examples/README.md, selecciona 1 o 2 libros que se acerquen al objetivo (por ejemplo, go y rust para un lenguaje; angular y typescript para un framework basado en TypeScript). Leer el body.html real ayuda a uniformar el tono del texto, la profundidad de las explicaciones, el tamaño de las secciones, la presentación de los ejemplos de código y la granularidad de las preguntas de repaso. Sin embargo, solo imites la forma de escribir; los hechos como versiones y funcionalidades deben volver a verificarse. No copies el texto de los ejemplos cambiando solo las palabras.
4. Escribe el manuscrito. Sigue references/components.md para los componentes HTML (recuadros, tablas, procedimientos, preguntas de repaso, títulos de errores, etc.), references/code-blocks.md para la forma de escribir los ejemplos de código, y references/writing-guide.md para la redacción del texto. Como hay muchos capítulos, es recomendable escribir unos cuantos a la vez, compilar y verificar.

6. Verificar los ejemplos de código

node <ruta_de_esta_skill>/scripts/build.mjs extract <ruta_de_la_carpeta_del_libro>   # Extrae los ejemplos de código a work/
node <ruta_de_esta_skill>/scripts/checkers/go-playground.mjs <ruta_de_la_carpeta_del_libro>   # Script de verificación según el lenguaje (ver tabla inferior)
node <ruta_de_esta_skill>/scripts/build.mjs render <ruta_de_la_carpeta_del_libro>    # Crea el HTML en dist/ con los resultados adjuntos

Script de verificación	Cuándo usarlo
checkers/go-playground.mjs	Go. Compila, ejecuta, ejecuta go vet y gofmt en el Go Playground oficial. Usa --share para crear un enlace compartido.
checkers/rust-playground.mjs	Rust. Compila, ejecuta y muestra sugerencias de tipos en el Rust Playground oficial.
checkers/typescript-local.mjs	TypeScript / JavaScript. Usa TypeScript instalado temporalmente para errores (con traducción oficial al japonés), globos de información y ejecución.
checkers/local-command.mjs	Python, Java, C#, etc. Verifica y ejecuta con un comando local (o instalado temporalmente).

Para lenguajes o frameworks que no están aquí (como Angular, que requiere mostrar la pantalla completa), crea un nuevo script de verificación que genere el mismo formato de resultados (work/results.json). Consulta references/code-blocks.md para el formato y references/verification.md para la metodología y ejemplos anteriores.

• Corrige hasta que render muestre «Requiere corrección: ninguno». Para los ejemplos que incluyen errores, escribe // ❌ en la línea (o // ⚠ para advertencias) para que en cada compilación se verifique que se produce el error esperado.
• Lee dist/report.txt y comprueba que los mensajes de error, los resultados de ejecución y las visualizaciones de tipos coinciden con las explicaciones del texto.
• Los elementos instalados temporalmente deben colocarse solo dentro de la carpeta temporal de la sesión, y la ubicación de la caché también debe apuntar allí (consulta references/verification.md).

7. Verificar visualmente

Ejecuta scripts/test_guide.py. dist/ será servido por este script en el puerto especificado de 127.0.0.1.

python <ruta_de_esta_skill>/scripts/test_guide.py --book <libro> --port 8770 --search "<término del texto>"

• Se necesita Playwright y Chromium de Python. Si no están instalados, pregunta al usuario si puede instalarlos (varios cientos de MB). Si no se puede instalar, omite esta verificación e indícalo en el informe.
• Corrige hasta que todas las pruebas pasen. Luego, revisa visualmente las capturas de pantalla en <libro>/shots/ (portada, instrucciones de uso, cada capítulo, tabla de referencia, modo oscuro, móvil) para asegurarte de que no haya desbordamientos, colores ilegibles ni roturas.
• También verifica que los enlaces externos del texto se abran y que los enlaces del playground se abran correctamente (abre uno de ellos y ejecútalo realmente).

8. Entregar y limpiar

1. Si se ha acordado crear un enlace compartido, créalo una vez que el texto esté confirmado (con --share) y verifica que todos los enlaces abran el código correcto.
2. Copia dist/full.html al escritorio del usuario (en Windows: C:\Users\<usuario>\Desktop; en macOS: ~/Desktop) como <nombre> Guía de introducción.html. Si ya existe un archivo con el mismo nombre, no lo sobrescribas; pregúntale al usuario.
3. Si el formato incluye una página compartida y el entorno dispone de la herramienta Artifact, llama a quickstart y luego publica dist/artifact.html (icon: book, description: una frase en el idioma del usuario). Indica que la página publicada es privada y que el usuario la comparte desde el menú Compartir. En entornos sin esta herramienta, omite este paso.
4. Elimina los elementos instalados temporalmente, la caché y las capturas de pantalla. Si tu trabajo ha escrito en ubicaciones compartidas (como la caché de npm), verifica y elimina solo tus archivos.
5. Informa en español: ubicación, URL de la página compartida (si se creó), contenido (resumen del esquema de capítulos), lo que se ha verificado (número de elementos) y notas importantes (entornos no verificados, limitaciones del playground, etc.).

Material de referencia

Archivo	Cuándo leerlo
references/questions.md	Cómo verificar la entrada y cómo preguntar las opciones de selección (plantilla de texto)
references/book-spec.md	Cómo escribir spec.json y book.json
references/writing-guide.md	Esquema de capítulos, redacción del texto y reglas de precisión
references/components.md	Componentes HTML del manuscrito
references/code-blocks.md	Cómo escribir ejemplos de código, atributos y formato de los resultados de los scripts de verificación
references/verification.md	Cómo verificar según el lenguaje, procedimiento de instalación temporal y limpieza
references/past-books.md	Esquemas de capítulos, colores, métodos de verificación y observaciones de los 4 libros anteriores
references/examples/README.md	Cómo seleccionar los ejemplos de manuscritos (extraídos de los 4 libros). Léelo antes de escribir el manuscrito