youtube-tutorials: Instructions file for Codex

Repository Instructions

This repo contains public teaching material for Owain's YouTube tutorials.

The quality bar is simple.

Each tutorial should feel like one clear lesson, not a folder of notes.

Before Editing

Read /Users/owainlewis/.codex/CONTEXT.md before writing or rewriting Owain's content.

Use tutorials/TUTORIAL-STANDARD.md as the source of truth for tutorial structure and writing style.

Use the YouTube skill when creating or rewriting a lesson.

Create A Tutorial

Use the scaffold command.

just new-tutorial my-topic "My Tutorial Title"

This creates:

tutorials/my-topic/
  README.md
  LESSON.md
  code/
  resources/
  resources/prompts.md
  resources/slides/

Do not hand-create a new tutorial folder unless the Justfile is unavailable.

After scaffolding, edit LESSON.md first.

The lesson is the source of truth.

Tutorial Standards

Every tutorial should have:

• README.md as the short entry point.
• LESSON.md as the one main teaching document.
• code/ for runnable code and setup files.
• resources/ for prompts, references, checklists, images, slides, and supporting files.
• resources/prompts.md for reusable prompts.
• resources/slides/ for polished slide decks or visual explainers.

Keep the tutorial root clean.

Move extra Markdown files into resources/ unless they are README.md or LESSON.md.

Tutorial-specific AGENTS.md and CLAUDE.md examples belong in resources/, not at the tutorial root.

If a reference file becomes required reading, fold the teaching back into LESSON.md.

Writing Standards

Write like Owain talks to a capable developer.

Use plain language.

Explain basics first, nuance second.

Use concrete commands, files, examples, and tradeoffs.

Use diagrams when they make the idea easier to understand.

Prefer Mermaid diagrams in LESSON.md.

Use slides when the idea needs visual polish for recording.

Avoid hype, guru phrasing, clever analogies, and em dashes.