Terryc21 · cdracars · Sep 2, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,21 @@
 
 All notable changes to `tutorial-creator` are documented here. This project adheres to [Semantic Versioning](https://semver.org/) and the format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased]
+
+### Added
+
+- **Codex support.** The skill now documents Codex installation and `$tutorial-creator`
+  invocation, includes Codex UI metadata, and renders follow-up commands using the
+  active runtime's syntax.
+
+### Changed
+
+- Claude Code and Codex deliberately share the existing `.claude/` project state and
+  registry paths, preserving one tutorial history when users switch agents.
+- Skill frontmatter now keeps version and author under the portable `metadata` key so
+  it validates under the Agent Skills format while retaining the same information.
+
 ## [2.0.1] — 2026-08-09
 
 A documentation and correctness patch. No new features; the surfaces, entry points, and schemas are unchanged from 2.0.0. Every item below was found by an audit pass over the shipped spec.

diff --git a/README.md b/README.md
@@ -16,6 +16,8 @@ Works with Swift, TypeScript, Python, and Rust.
 
 ## Try it
 
+### Claude Code
+
 ```bash
 /plugin marketplace add Terryc21/tutorial-creator
 /plugin install tutorial-creator@tutorial-creator
@@ -27,6 +29,22 @@ Then, in any Claude Code session:
 /skill tutorial-creator
 ```
 
+### Codex
+
+Clone the repository and link the skill folder into your personal Codex skills:
+
+```bash
+git clone https://github.com/Terryc21/tutorial-creator ~/src/tutorial-creator
+mkdir -p ~/.codex/skills
+ln -s ~/src/tutorial-creator/skills/tutorial-creator ~/.codex/skills/tutorial-creator
+```
+
+Then, in Codex:
+
+```
+$tutorial-creator
+```
+
 Pick **"Write a tutorial for myself"**, then **"Topic + file"**, and point it at any file
 you've worked on recently. About ten minutes later you have a real lesson.
 
@@ -42,17 +60,24 @@ won't find it.
 git clone https://github.com/Terryc21/tutorial-creator ~/src/tutorial-creator && ln -s ~/src/tutorial-creator/skills/tutorial-creator ~/.claude/skills/tutorial-creator
 ```
 
-For one project only, link into that project's skills folder instead:
+For one Claude Code project only, link into that project's skills folder instead:
 
 ```bash
 mkdir -p /path/to/project/.claude/skills && ln -s ~/src/tutorial-creator/skills/tutorial-creator /path/to/project/.claude/skills/tutorial-creator
 ```
 
+For one Codex project only, link into that project's agent skills folder instead:
+
+```bash
+mkdir -p /path/to/project/.agents/skills && ln -s ~/src/tutorial-creator/skills/tutorial-creator /path/to/project/.agents/skills/tutorial-creator
+```
+
 </details>
 
-**New to Claude Code?** A *skill* is a set of written instructions Claude Code knows how
-to follow. Type `/skill tutorial-creator` and it asks what you want, then does it. There
-is nothing to memorise — it walks you through every choice.
+**New to agent skills?** A *skill* is a set of written instructions an agent knows how
+to follow. Type `/skill tutorial-creator` in Claude Code or `$tutorial-creator` in Codex
+and it asks what you want, then does it. There is nothing to memorise — it walks you
+through every choice.
 
 ---
 

diff --git a/USAGE.md b/USAGE.md
@@ -20,8 +20,10 @@ Every command, setting, and option. If you just want to try the skill, the
 
 ## Commands
 
-Type `/skill tutorial-creator` on its own and the skill asks what you want. Everything
-below is a shortcut for people who already know.
+Invoke the skill with `/skill tutorial-creator` in Claude Code or `$tutorial-creator`
+in Codex. The examples below use the Claude Code spelling; in Codex, replace
+`/skill tutorial-creator` with `$tutorial-creator`. Invoke it without arguments and the
+skill asks what you want. Everything below is a shortcut for people who already know.
 
 ```
 /skill tutorial-creator                        # ask me what I want to do
@@ -203,7 +205,10 @@ The first time you run it, the skill asks five things:
 4. How experienced you are
 5. Which code you're learning from, if that's a different folder
 
-Your answers go in `.claude/tutorial-config.yaml`. Edit it any time.
+Your answers go in `.claude/tutorial-config.yaml`. Edit it any time. The same file is
+used from Claude Code and Codex, so switching agents preserves your tutorials,
+vocabulary, and progress. The directory name is retained for backward compatibility;
+Codex treats it as tutorial-creator data, not as Codex configuration.
 
 One thing to know: that file goes **in the project folder you chose**, which isn't
 necessarily the folder you were sitting in when you ran the command. The skill then

diff --git a/skills/tutorial-creator/AUDIENCE.md b/skills/tutorial-creator/AUDIENCE.md
@@ -30,7 +30,7 @@ Future audits may flag these as "missing"; they are deliberate choices for Path
 1. **Read config.** `.claude/tutorial-config.yaml`. Required fields: `language`, `project_dir`. `experience_level` is read but the audience-facing render uses the audience answer (step 4) instead.
 2. **Receive topic + source.** The user provides both. If only one is provided, route them to entry [c] (synthesized example) for topic-only, or ask for a topic for source-only.
 3. **Read the source file.** Identify the line range that demonstrates the topic (use the same matching heuristic as SKILL.md Entry [c] step 3, but skip the candidate-ranking step; the user has already chosen the file).
-4. **Ask the four routing questions.** Via AskUserQuestion, in this order:
+4. **Ask the four routing questions.** Use the runtime's structured question tool or plain text, in this order:
    - **Audience:** beginner / intermediate / senior / mixed
    - **Honest-machine opt-in:** Y / N (asks "Append a section on what this article does NOT cover and what's still uncertain?")
    - **Length budget:** S / M / L / X (show the venue's word count for each tier, resolved from `venues/_schema.yaml` — that file is authoritative if it ever disagrees with a venue file's front-matter or calibration table)
@@ -44,7 +44,7 @@ Future audits may flag these as "missing"; they are deliberate choices for Path
    - `length_budget` (one of S/M/L/X, with resolved word target + ceiling)
    - `honest_machine_optin` (boolean)
    - The user's `vocabulary.yaml` (for terminology alignment)
-6. **Write the artifact.** Save to a path the user picks (default: `./audience-artifacts/<venue>-<topic-slug>.md`). The skill does not insert the artifact into a venue's CMS or post it; the user does that step manually. Tell the user, in one line, that the artifact is not session-logged and `/skill tutorial-creator undo` will not revert it (that command reverts the last *tutorial* generation, a different file) — to remove it, delete the file directly. See `## Asymmetries with Path 1` for why Path 2 has no recovery hook.
+6. **Write the artifact.** Save to a path the user picks (default: `./audience-artifacts/<venue>-<topic-slug>.md`). The skill does not insert the artifact into a venue's CMS or post it; the user does that step manually. Tell the user, in one line, that the artifact is not session-logged and `<invoke> undo` will not revert it (that command reverts the last *tutorial* generation, a different file) — render `<invoke>` for the current runtime, and tell the user to delete the artifact directly if they want to remove it. See `## Asymmetries with Path 1` for why Path 2 has no recovery hook.
 
 ### Honesty rule
 

diff --git a/skills/tutorial-creator/SCHEMAS.md b/skills/tutorial-creator/SCHEMAS.md
@@ -7,6 +7,10 @@ when a schema changes, update this file first, then the surfaces that touch it.
 **Status:** v2.0 baseline. Versioned at the bottom of each schema.
 **Last updated:** 2026-05-10 (Phase 6.5: Schema 5 added for cross-project registry; `$PROJECT_ROOT` clarified throughout).
 
+The `.claude/` locations below are tutorial-creator's established data paths, shared by
+Claude Code and Codex. The name is retained for backward compatibility so both runtimes
+read and update the same learning history.
+
 ---
 
 ## Files at a glance
@@ -315,7 +319,7 @@ The registry is a single-writer file. The skill does not currently take a lock w
 
 ### Why not just walk to a known location?
 
-An earlier design considered "always look at `~/.claude/tutorial-creator/<project-name>/` for configs." The registry is a cleaner separation: configs stay with their projects (so a project moves with a `git mv` or `mv` of the project directory), and the registry is just a pointer table. Same separation `git` uses between `.git/` directories and a hypothetical `git config --global` registry — except `git` doesn't actually need a registry because it always operates on cwd. tutorial-creator does need one because invocations from arbitrary cwds are the common case (`/skill tutorial-creator status` from anywhere should work).
+An earlier design considered "always look at `~/.claude/tutorial-creator/<project-name>/` for configs." The registry is a cleaner separation: configs stay with their projects (so a project moves with a `git mv` or `mv` of the project directory), and the registry is just a pointer table. Same separation `git` uses between `.git/` directories and a hypothetical `git config --global` registry — except `git` doesn't actually need a registry because it always operates on cwd. tutorial-creator does need one because invocations from arbitrary cwds are the common case (`status` from anywhere should work).
 
 ### v1 → future migration