Beginner Reference Book

Create a Beginner Reference Book (Introductory Guide)

Create an introductory reference book for a programming language or framework, following the same design, features, and approach as the existing beginner's guides for TypeScript, Rust, Angular, and Go (samples in references/examples/). The output consists of two items:

• A single-file HTML file placed on the desktop (<Language> Beginner's Guide.html, opens by double-clicking)
• A shared page on claude.ai (private; the user shares it via the Share menu). Only created when the Artifact tool is available (e.g., Claude Code)

To maintain a consistent design, the appearance and behavior reuse the skill's components (assets/ and scripts/) as-is. Do not rewrite the CSS or JavaScript each time. Only write the book's content (manuscript) and the method for verifying code for the specific language.

The core value of this reference book is that all code and results are genuinely correct. Code examples, error messages, and execution results must always be verified with the actual compiler or official playground (do not invent them). Version and feature explanations must also be confirmed using official release notes.

This is a long task taking several hours. At key milestones, inform the user in 1-2 sentences about what you are doing.

1. Verify the Input

The input is either the text written after the skill name (often appended as ARGUMENTS: at the end of this skill's body) or the language/framework name from the user's request.

• When nothing is written: Do not start working. Ask back: "Which programming language or framework would you like a reference book for?" (Use AskUserQuestion with up to 4 candidates like Python, Java, React, Vue.js. Allow 'Other' for free-form input).
• When something other than a programming language or framework is written: Explain the reason in one sentence and ask the user to re-enter a language or framework. Verify the re-entered input similarly, and do not proceed until correct input is provided.
• Handling ambiguous input, variations, or multiple specifications: See references/questions.md under "How to verify input". If in doubt, always read it.

In environments where AskUserQuestion is not available, ask the same content in plain text and stop there.

2. Do Preliminary Research Before Asking Questions

To correctly write descriptions for the options, verify the following before asking (take a few minutes; no large downloads yet):

1. Latest stable version and release date: Check the official website or release notes. Used for the "Compatible with " badge on the cover.
2. Official playground (official website that runs in a browser): If available, check if there is an API to send code for compilation/execution, if codes can be opened via URL, or if it uses a share-link (server-saved code) method.
3. Whether it is already installed on the computer (e.g., python --version). If not, the size of a temporary installation (official download size).
4. Available disk space (Windows PowerShell: Get-PSDrive C, Git Bash: df -h /c, macOS/Linux: df -h ~).
5. User environment rules (CLAUDE.md, AGENTS.md, etc.). For example, if there is a rule like "Do not touch folders synced with the cloud (e.g., OneDrive)", follow it from research to cleanup.

Methods for researching and language-specific verification candidates are in references/verification.md.

3. Ask Selection Items (Same Items as Before)

Using AskUserQuestion, ask the following four items in one go. Format the items and options the same way as when creating previous reference books (templates in references/questions.md). Place the recommended option first and mark it with "(Recommended)". In environments without AskUserQuestion (e.g., Codex), present the same four questions and options as a numbered list (include the chapter outline in the preview) and wait for answers.

1. Target audience: e.g., "JS/TS experienced (Recommended)", "Programming beginner". For frameworks built on TypeScript (e.g., Angular, NestJS), use "TypeScript experienced (Recommended)"; for Python frameworks (e.g., Django), use "Python experienced (Recommended)". Adapt to the subject.
2. Scope: "Basics only (short, 8-9 chapters)", "Basics + common features (Recommended, 12-14 chapters)", "Up to advanced topics (long, 16-18 chapters)". Show the chapter outline in the preview for each.
3. Format: "Same format as before (Recommended)" = single-file HTML on desktop + shared page, with review questions, code copy, reading progress tracking, and keyword search. Other options: "HTML file only", "Select features". In environments where a shared page cannot be created (no Artifact tool), the "Same format as before" becomes just the HTML file. In that case, omit "HTML file only" and do not mention the shared page in the description.
4. Verification method: Based on preliminary research, list only available methods. e.g., "Verify with official Playground", "Temporarily install and verify", "Verify with already installed ". When disk space is low, recommend a method that does not install anything on the computer.

Depending on the answers, ask once more if necessary:

• "Select features" → Ask via multi-select: chapter review questions, code copy button, reading progress check, glossary, keyword search.
• If the playground used for verification uses a "share-link method" (like Go Playground, which saves code to a server and creates a link), ask: "Create shared links" or "Copy and paste". Shared links are public and cannot be deleted, so you must obtain consent. Playgrounds that open code via URL (Rust, TypeScript) do not save, so you may skip this question.

All selected options must be respected throughout the subsequent work. Do not re-ask what has already been asked.

4. Plan

1. Define the chapter outline (see references/writing-guide.md). Each chapter should be readable in about 10 minutes. For languages, the final chapter should be "How to read common errors". The outlines of the previous four books are in references/past-books.md.
2. Write spec.json (see references/book-spec.md for items and examples). Includes: cover name, version, target audience, chapter titles, code language, playground opening method, accent color (brand color), etc.
3. Accent color: Use the official brand color of the language or framework. The script scripts/make_palette.mjs generates light and dark colors from one color and checks for readable contrast (called automatically by new_book.mjs).

5. Create the Template and Write the Manuscript

1. Create the working folder inside the session's temporary folder (e.g., Claude Code's scratchpad, or a new folder in the OS temp folder). Do not create it under a cloud-synced folder (e.g., OneDrive).
2. Create the template: node <this-skill>/scripts/new_book.mjs <book-folder> --spec spec.json
   • Generates: book.json, palette.json, src/body.html, src/ja-errors.json.
   • src/body.html already contains the table of contents, cover, usage instructions, chapter frames, review question frames, and appendix frames. Replace all <!-- TODO … --> placeholders (if any remain, the build step will report "Needs fix").
3. Before writing, read the samples. references/examples/ contains manuscripts extracted from the four previous books: cover, usage instructions, one representative chapter, the error chapter, and appendices (all assembled and verified with this skill's components). Use the table in references/examples/README.md to select 1-2 samples close to your target (e.g., for a language, choose go and rust; for a framework built on TypeScript, choose angular and typescript). Reading actual examples aligns the tone, depth of explanations, section sizes, code presentation, and granularity of review questions better than reading rules. However, only mimic the writing style; always re-verify version numbers, features, and other facts. Do not copy sample text and simply replace words.
4. Write the manuscript. Follow references/components.md for HTML components (callouts, tables, procedures, review questions, error headings, etc.), references/code-blocks.md for code examples, and references/writing-guide.md for writing style. Since there are many chapters, it is recommended to write a few chapters at a time, then build and verify.

6. Verify Code Examples

node <this-skill>/scripts/build.mjs extract <book-folder>   # Extract code examples to work/
node <this-skill>/scripts/checkers/go-playground.mjs <book-folder>   # Verification script matching the language (see table below)
node <this-skill>/scripts/build.mjs render <book-folder>    # Create HTML in dist/ with verified results

Verification Script	Use Case
checkers/go-playground.mjs	Go. Compile, run, go vet, gofmt on the official Go Playground. --share creates shared links.
checkers/rust-playground.mjs	Rust. Compile, run, type hints on the official Rust Playground.
checkers/typescript-local.mjs	TypeScript/JavaScript. Temporarily installed TypeScript for errors (with official Japanese translations), tooltips, and execution.
checkers/local-command.mjs	Python, Java, C#, etc. Verify and run using an already-installed or temporarily installed command.

For languages or frameworks not listed here (e.g., Angular, where you want to show the rendered UI), create a new verification script that writes results in the same format (work/results.json). See references/code-blocks.md for the result format, and references/verification.md for design principles and past examples.

• Fix until render reports "Needs fix: none". For examples that should show errors, write // ❌ (or // ⚠ for warnings) on the line to verify expected errors are produced during each build.
• Read dist/report.txt and confirm that error messages, execution results, and type displays match the explanations in the manuscript.
• If anything was temporarily installed, keep it only inside the session's temporary folder and point its cache location there (see references/verification.md).

7. Verify on Screen

Run scripts/test_guide.py. The script serves dist/ on 127.0.0.1 at the specified port.

python <this-skill>/scripts/test_guide.py --book <book> --port 8770 --search "<word from the manuscript>"

• Requires Python's Playwright and Chromium. If not installed, ask the user for permission to install them (a few hundred MB total). If installation is declined, skip this verification and report that in the delivery note.
• Fix until all tests pass. Then visually inspect the screenshots in <book>/shots/ (cover, usage instructions, each chapter, quick reference, dark mode, mobile) for overflow, hard-to-read colors, or layout issues.
• Also verify that external links in the manuscript open correctly, and that at least one Playground link opens and runs the code.

8. Deliver and Clean Up

1. If shared links are to be created, do so after the manuscript is finalized (using --share), and verify all links open the correct code.
2. Copy dist/full.html to the user's desktop (Windows: C:\Users\<user>\Desktop, macOS: ~/Desktop) as <Name> Beginner's Guide.html. If a file with the same name exists, ask the user before overwriting.
3. If the format includes a shared page and the Artifact tool is available, call quickstart and then publish dist/artifact.html (icon: book, description: one sentence in Japanese). Inform the user that the published page is private and they can share it via the Share menu. Skip this step in environments where Artifact is not available.
4. Remove temporarily installed tools, caches, and screenshots. If your work wrote to shared locations (e.g., npm cache), verify and clean only your own data.
5. Report in Japanese: location, shared page URL (if created), content (key points of the chapter outline), verification summary (count of verified items), and caveats (unverified environments, Playground limitations, etc.).

Reference Materials

File	When to Read
references/questions.md	How to verify input and how to ask selection items (phrasing templates)
references/book-spec.md	How to write spec.json and book.json
references/writing-guide.md	Chapter outline, writing style, accuracy rules
references/components.md	HTML components for the manuscript
references/code-blocks.md	Code example formatting, attributes, and verification script result format
references/verification.md	Language-specific verification methods, temporary installation procedures and cleanup
references/past-books.md	Chapter outlines, colors, verification methods, and lessons learned from the previous four books
references/examples/README.md	How to select manuscript samples (extracts from the four books). Read before writing the manuscript