# Tutorial Creator
An Agent Skill for building, studying, auditing, and redesigning source-grounded
interactive tutorials and web books.
Turn a paper, manual, book, or source repository into a learning experience whose
claims have citations and whose interactions explain a mechanism. Choose a
structure that fits the subject: a proof studio for a derivation, a systems map
for architecture, or a workflow debugger for an operational procedure.
## Install and start
Install with the [Skills CLI](https://github.com/vercel-labs/skills):
```bash
npx skills add voidful/tutorial-creator
```
For manual Codex installation, copy the complete directory to
`~/.agents/skills/tutorial-creator/` for personal use or
`.agents/skills/tutorial-creator/` in a project. Keep `references/`, `assets/`,
`examples/`, and `scripts/` beside `SKILL.md`. See
[Codex skill discovery](https://learn.chatgpt.com/docs/build-skills) for the
current supported locations.
Then ask your agent:
```text
Use $tutorial-creator to turn this paper into a Traditional Chinese tutorial
for engineers who know basic probability. Build chapters 1–3 for local use,
keep precise source references, and add a lab where it improves understanding.
Finish the requested chapters and verify the result.
```
The agent uses the tools available in its host. This bundle does not require a
particular model or an API key. Browser inspection, document extraction, and
site builds need suitable tools in the target environment.
## Choose a task
| Task | Example | Result |
| --- | --- | --- |
| Build | `tutorial-creator build ./paper.pdf` | A verified tutorial for the requested scope. |
| Study | `tutorial-creator study https://example.org/tutorial` | A diagnosis of learning structure and transferable design choices. |
| Audit | `tutorial-creator audit ./existing-tutorial` | Findings with evidence, severity, and concrete fixes; no edits by default. |
| Redesign | `tutorial-creator redesign ./chapters/memory` | Improvements to the requested learning, interaction, or visual structure. |
These are instructions to an agent, **not executable shell commands**.
Natural language works too; "audit and fix" includes the fixes. For a small
change, ask for it directly:
```text
Use $tutorial-creator to fix this lab's reset behavior. Keep the chapter
structure and existing source map, check the affected model and UI states,
and report what you verified.
```
More examples, including PDF ingestion and Bradley–Terry labs, are in
[繁體中文使用 prompts](CODEX_USAGE_PROMPTS.zh-TW.md).
## How the skill works
- **Evidence before claims.** Preserve source locations, distinguish source
facts from derived or illustrative examples, and carry attribution.
- **Learning structure before appearance.** Eight macrostructures and a
seven-axis fingerprint help select how the learner reads, predicts, traces,
compares, or diagnoses.
- **One model per lab.** Formula, result, plot, explanation, and static example
must agree with a deterministic oracle.
- **A useful reading core.** Core content remains navigable without JavaScript;
preserve accessibility and the project's offline promise.
- **Work sized to the request.** A local fix uses local evidence and checks. A
new tutorial uses persistent source, learning, interaction, and design
contracts. Interaction files are needed only for warranted labs.
The build workflow starts with a representative chapter when useful, then
continues through the requested coverage. Existing permissions and project
choices carry forward within their scope. Checks focus on changed behavior;
full release gates apply when delivering a new tutorial or assessing a release.
## What is included
| Included in this repository | Separate companion implementation |
| --- | --- |
| Skill instructions and four task modes | A standalone tutorial compiler CLI |
| Six JSON Schemas, templates, and linked IR examples | PDF extraction and OCR pipeline |
| Bradley–Terry interaction specification and numeric fixture checks | A production Astro/React tutorial and executable lab |
| Three dependency-free Python validators | Browser, accessibility, and learner evaluations |
| Design, pedagogy, rights, and verification references | Hosting and deployment |
The [companion implementation prompt](CODEX_IMPLEMENTATION_PROMPT.md),
[architecture](ARCHITECTURE.md), and
[implementation plan](IMPLEMENTATION_PLAN.zh-TW.md) describe that separate
product. Load them when implementing it; installing this skill does not install
or run that toolchain.
## Validate this bundle
Python 3.10 or newer is sufficient; no Python packages are required:
```bash
python3 scripts/check_skill_health.py
python3 scripts/validate_manifest.py examples/tutorial-manifest.json --strict-warnings
python3 scripts/validate_site.py examples/static-site --offline --strict-warnings
```
For machine-readable health output, use
`python3 scripts/check_skill_health.py --json` instead of the first command.
The health check covers package structure, frontmatter, local documentation
links, agent metadata, schemas, examples, cross-IR references, numeric fixture
consistency, and `MANIFEST.sha256`. The other two commands validate the supplied
manifest and static HTML fixture.
These checks validate the bundle and fixtures. They do not establish real PDF
extraction quality, browser behavior, WCAG conformance, teaching effectiveness,
or completion of the companion compiler. For a generated tutorial, select
checks with [the verification guide](references/verification.md).
## Source use and publication
Record the permissions relevant to the intended output. Unknown rights do not
authorize public redistribution. Keep unresolved source and asset permissions
visible, preserve attribution, and restrict affected material to its authorized
use. A request to edit a tutorial does not itself grant new source rights or
permission to send confidential content to another service. See
[licensing and security](references/licensing-security.md).
## Version and design references
Skill bundle: **0.3.0**. The six IR schemas are unchanged: Design IR is
`0.2.0`; Source, Learning, Interaction, Book, and Rights remain `0.1.0`.
See the [changelog](CHANGELOG.md).
Version 0.3 revisits instruction scope using two references, read on
2026-09-07:
- [Eric Provencher, “Rethinking skills and prompts for GPT-6 Astra”](https://x.com/pvncher/status/2095991462416490862):
shorter discovery text, selective reference loading, and removal of
unnecessary workflow prescriptions.
- [OpenAI's GPT-6 Astra guidance](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-6-astra):
clearer completion and authorization boundaries, writing preferences, and
testing proportional to the task.
These inform the skill's instructions; this release does not claim a measured
model-performance improvement or require GPT-6 Astra. Model settings remain the
host's responsibility.
The structure selection and study/audit/redesign approach also draws on
[Hallmark](https://github.com/Nutlope/hallmark) (MIT). Tutorial Creator defines
its own learning structures, evidence contracts, and verification rules.
Hallmark's themes, branding, and visual assets are not included.
[MIT license](LICENSE).