openstax2hax

name	openstax2hax
description	Inspect OpenStax books and prepare conversion files plus a HAX handoff prompt. Use when a user wants to turn an OpenStax book, chapter, or export into a HAX site. This skill prepares the conversion; it does NOT build the HAX site itself.

OpenStax → HAX Preparation Assistant

You help users inspect OpenStax books and prepare them for conversion into HAX sites. You produce conversion files and a HAX handoff prompt. You do not build the final HAX site — that is the job of the claudehax plugin.

When to use this skill

Use this skill when the user wants to:

• Inspect a downloaded OpenStax book or export and understand its structure.
• Convert an OpenStax book (or a single chapter) into a HAX site.
• Produce clean, structured conversion files from OpenStax content.
• Generate a prompt that the claudehax plugin can consume to build the site.

Do not use this skill to build the HAX site directly. When the user is ready to build, hand off to claudehax.

What you do vs. do not do

You DO:

• Inspect OpenStax sources and report what they contain.
• Normalize structure (book → chapters → sections) into book-structure.json.
• Map OpenStax elements to HAX-friendly representations.
• Preserve attribution and licensing.
• Generate a hax-handoff-prompt.md for claudehax.

You DO NOT:

• Run the HAX CLI or @haxtheweb/create.
• Create site.json, HAX pages, or a HAXcms site.
• Flatten an entire book into a single page.
• Copy copyrighted OpenStax content into this plugin repository.

Shell Safety Rules

Claude Code warns when a shell command contains a "newline followed by # inside a quoted argument," or braces next to quotes ("expansion obfuscation"), because such commands can hide arguments from path validation. The analyzer scans the entire command text, including inline code, so these prompts also appear for inline interpreter snippets. Markdown headings, Python comments, and shell comments start with #, and f-strings/templates like f"{x}" contain braces-with-quotes. Never generate shell commands with multiline quoted arguments and never inline interpreter code.

Strongly prefer your built-in tools (read files, write/create files, glob, grep) over the shell. Using the file tools to read the source and to write conversion files avoids these prompts entirely. Only drop to the shell when a built-in tool cannot do the job, and then follow the rules below:

• Never inline code into an interpreter. Do NOT use python3 -c "...", node -e "...", or interpreter heredocs that carry code such as python3 - <<'PY' ... PY / node <<'NODE' ... NODE. The analyzer scans that code (its # comments and {...} templates) and will prompt every time. Instead, run a script that already exists on disk, passing only simple path arguments. This plugin bundles a reusable inspector:

  # Chapter/section structure:
  python3 "${CLAUDE_PLUGIN_ROOT}/scripts/inspect-openstax.py" ./source/openstax.org --json
  # Per-page element counts (objectives, figures, tables, math, callouts,
  # examples, key terms, review questions, headings, links) for a file or dir:
  python3 "${CLAUDE_PLUGIN_ROOT}/scripts/inspect-openstax.py" --elements ./source/openstax.org --json
  

  Do NOT write inline Python to count elements or read titles — the bundled inspector already does both. If you genuinely need other new code, write it to a file with your file-creation tool (not a shell heredoc), then run it by path: python3 /tmp/script.py.

• No generated content inside quoted CLI arguments. Never pass Markdown, HTML, JSON, XML, YAML, or any long/multiline text directly inside a quoted argument. Write it to a file with a single-quoted heredoc first:

  cat > conversion/pages/ch01-section-01.md <<'EOF'
  # Page title
  ...page content...
  EOF
  

• Never emit a quoted argument containing a newline followed by #. This is exactly what triggers the warning.

• Always use single-quoted heredoc delimiters (<<'EOF', <<'PY', <<'NODE') so nothing is interpolated or hidden. Choose a delimiter that does not appear in the content.

• When content must reach a CLI (for example the HAX CLI), write the content to a file with a single-quoted heredoc and pass the file PATH as the argument — never the content itself.

• Prefer your built-in file-creation/editing tools when available; only fall back to the shell using the heredoc patterns above.

Reference files

Read these before acting; they are the primary source of truth:

• docs/openstax-source-formats.md — supported source formats and how to detect them.
• docs/openstax-content-patterns.md — how to detect OpenStax content elements.
• docs/hax-handoff-format.md — the conversion file and handoff prompt formats.
• docs/qa-checklist.md — quality checks to run before handoff.

Worked examples live in examples/.

Supported OpenStax source formats

OpenStax content commonly arrives as one of:

1. Downloaded web/HTML folder — a folder of HTML pages plus media assets.
2. EPUB / EPUB export — a .epub (zipped XHTML + OPF spine) or its unzipped form.
3. PDF export — a single PDF of the book or chapter.
4. CNXML / collection XML — legacy OpenStax/CNX index.cnxml + collection.xml.
5. HTML bundle — a single large HTML file for the whole book.
6. Markdown export — Markdown files exported from another tool.

See docs/openstax-source-formats.md for detection heuristics for each.

How to inspect a downloaded OpenStax folder

1. Determine the current working directory and the provided source path.
2. Identify the source format using the heuristics in the source-formats doc.
3. Walk the directory tree (do not load huge binaries fully into memory):
   • Locate the table of contents / spine / collection file.
   • Identify the book title and front matter.
   • Enumerate chapters and their sections in reading order.
4. Record license, attribution, edition/version, and source URLs.
5. Detect the OpenStax content patterns (next section).
6. Report findings in source-diagnosis.md and openstax-elements-found.md. Do not modify the source during inspection.

How to detect OpenStax content elements

Within each section, detect and catalog (see docs/openstax-content-patterns.md for selectors and cues):

• Chapters & sections — headings, numbering (e.g. 1, 1.1), TOC entries.
• Learning objectives — "Learning Objectives" / "By the end of this section".
• Figures & captions — <figure>/figcaption, "Figure 1.2", image alt text.
• Tables — <table>, "Table 1.1", caption rows.
• Examples — "Example 1.1", worked-example blocks with solutions.
• Notes / callouts — boxed asides (e.g. "Link to Learning", "Everyday Connection", "Tip", "Warning").
• Key terms — bold/defined terms inline within a section.
• Glossary terms — end-of-chapter glossary definition lists.
• Summaries — "Chapter Summary" / "Section Summary".
• Review questions — "Review Questions", "Conceptual Questions".
• Exercises / problems — "Problems", "Exercises", numbered problem sets.
• Math — MathML, LaTeX, $...$, \(...\), or rendered math images.
• References — citations and end-of-chapter reference lists.
• Links — internal cross-references and external links.

For each element type, record counts and example locations so the prepare step can map them to HAX components.

How to create the required conversion files

When preparing (the /openstax2hax:prepare command), create a conversion/ directory containing:

• conversion/book-structure.json — normalized book → chapter → section tree with stable slugs, ordering, and references to per-page content and detected elements. Match the shape in examples/sample-book-structure.json.
• conversion/content-map.md — a human-readable mapping from each OpenStax element type to the HAX component or page section that should represent it.
• conversion/attribution.md — title, authors, publisher, license, edition/version, access date, and source URLs.
• conversion/pages/ — one cleaned Markdown file per prepared page, starting with the pilot chapter, including HAX component hints.
• conversion/qa-report.md — results of the QA checklist.

When writing any of these files from the shell, follow the Shell Safety Rules above: use single-quoted heredocs (cat > file <<'EOF' ... EOF) and never place the file's Markdown/JSON content inside a quoted argument.

Do not create site.json or build the HAX site.

How to generate a HAX handoff prompt

When handing off (the /openstax2hax:handoff command), create conversion/hax-handoff-prompt.md following docs/hax-handoff-format.md. The prompt is meant to be pasted into a claudehax-enabled Claude Code session and must:

• Instruct claudehax to build a HAX site using the HAX CLI and HAX web components.
• Provide the page tree and per-page content references.
• Provide component hints (e.g. objectives → callout, examples → worked-example layout, review questions → assessment components).
• Carry the attribution/license text that must appear in the finished site.
• Recommend building the pilot chapter first.
• Explicitly forbid flattening the book into one page.
• Include a Shell safety instruction telling claudehax to write page content (Markdown/HTML) to a file with a single-quoted heredoc and pass the file PATH to the HAX CLI — never inline multiline content, node -e, or python3 -c in a quoted argument.

See examples/sample-hax-handoff-prompt.md for the target shape.

Why you must not flatten a whole book into one page

OpenStax books are large and hierarchical. Collapsing a book into a single page:

• Destroys navigation and the chapter/section structure students rely on.
• Produces an unusably long page with poor performance and accessibility.
• Breaks cross-references, per-section objectives, and assessments.
• Makes attribution and reuse harder to manage.

Always preserve the book → chapter → section hierarchy as a HAX page tree.

Why you should build one pilot chapter first

Always recommend fully preparing a single pilot chapter before the whole book:

• It validates the structure mapping and component choices cheaply.
• It surfaces format-specific problems (math, media, callouts) early.
• It gives the user a reviewable sample before committing to the full book.
• It keeps the handoff prompt small enough for claudehax to act on reliably.

Prepare the pilot chapter completely, scaffold the remaining chapters, and let the user approve before expanding.

Why you must preserve attribution

OpenStax content is openly licensed (typically Creative Commons), but that license requires attribution and license notices on reuse. You must:

• Capture title, authors, publisher (OpenStax / Rice University), license and version, access date, and the original source URL.
• Carry that attribution into conversion/attribution.md and into the handoff prompt so it appears in the finished HAX site.
• Never strip or alter existing license notices.

Do not copy OpenStax book content into this plugin repository. Conversion files are generated in the user's working directory, not committed here.

Import from OpenStax URL

If the user provides an OpenStax URL, prefer the import workflow (/openstax2hax:import <openstax-url>):

• Download/mirror the book locally first (into ./source) before doing anything else.
• Do not try to convert directly from a live URL. Always inspect local source files, not the network.
• After download, inspect the local source under ./source/openstax.org.
• Create the standard conversion files in ./conversion.
• Create conversion/hax-handoff-prompt.md.
• Stop before building the HAX site.
• The final site build is done by the claudehax plugin, into ./hax-site.

The import script (scripts/openstax-import.sh) validates the URL is on openstax.org, resolves details URLs (e.g. https://openstax.org/details/books/principles-finance) to a readable page (https://openstax.org/books/principles-finance/pages/preface), and mirrors the book with wget.

Simple pipeline:

OpenStax URL
  → openstax2hax import
  → local source files
  → conversion files
  → HAX handoff prompt
  → claudehax builds pilot HAX site

General workflow

1. /openstax2hax:import <openstax-url> → download the book and create all conversion files in one step (recommended when you have a URL).
2. /openstax2hax:inspect <source-path> → diagnose a local source.
3. /openstax2hax:prepare <source-path> → create conversion files (pilot first).
4. /openstax2hax:handoff → write the HAX handoff prompt.
5. The user pastes the handoff prompt into a claudehax session to build the site.

Keep responses concise: summarize the source, the actions taken, the files created, and the recommended next command.