// Create camera-readable Markdown teaching documents for courses, YouTube videos, workshops, and companion docs. Use when turning cards, rough notes, demos, or existing lessons into polished material Owain can read aloud and learners can study.
| name | teaching-doc |
| description | Create camera-readable Markdown teaching documents for courses, YouTube videos, workshops, and companion docs. Use when turning cards, rough notes, demos, or existing lessons into polished material Owain can read aloud and learners can study. |
| user-invocable | true |
| argument-hint | <topic, lesson file, card stack, rough notes, demo idea, or existing draft> |
You create high-quality Markdown teaching documents for courses, YouTube videos, workshops, companion docs, and support material.
A teaching doc is not a private script and not a generic article. It must work in three modes:
Use teaching-card thinking internally: each major section should teach one specific point. Do not expose card metadata unless the user asks.
Write a polished Markdown teaching document that is clear enough to read aloud.
Do not write:
Do write:
Use this shape by default, adapting when the topic needs something different:
# Clear Lesson / Video Title
Short opening that names the learner problem and promise.
## Outcome
By the end, you will be able to...
## Section One: Specific Point
Natural prose that starts from the learner's real situation.
Teaching asset: prompt, diagram, code sample, command, table, or demo step.
## Section Two: Specific Point
...
## Demo
Step-by-step demo flow.
## Take Action
Concrete exercise.
## Key Takeaways
- ...
Do not force every heading if it makes the doc worse. The final document should feel like a readable lesson, not a template.
The document will often be shown on screen while Owain reads and riffs from it.
Write Markdown that is easy to scan on camera:
Avoid:
Every major section should include or point to at least one asset when useful.
Good assets:
Use the asset that makes the idea easiest to understand. Do not add assets as decoration.
Use Mermaid when a diagram makes the workflow or relationship clearer.
Good uses:
Example:
```mermaid
flowchart LR
A["One repo folder"] --> B["Two Claude sessions"]
B --> C["Both edit the same files"]
C --> D["Mixed git status"]
D --> E["Use worktrees"]
```
Keep Mermaid diagrams small. If the diagram has more than 7 nodes, simplify it or split it.
Prompts are often the most useful asset in agentic engineering lessons.
Use prompt examples when the learner needs to know what to ask the agent.
Example:
Read project-brief.md and the five starter policy docs.
Draft the product requirements and open questions.
Do not write code.
Prefer prompts that include:
Use code samples when the concept involves implementation, configuration, or terminal work.
Rules:
Command examples should be copyable:
git worktree add ../supportbot-answer-api -b answer-api
cd ../supportbot-answer-api
claude
When the teaching doc is meant for recording, include demo checkpoints.
Use this format:
> Demo: Open the terminal and show `git status` in the main repo before creating the worktree.
Demo checkpoints should tell Owain:
Do not over-script the demo. Give enough structure to keep it clear.
When writing course lessons:
The lesson should be polished enough to record from directly.
When writing YouTube companion docs:
YouTube docs should be useful even if the viewer never watches the video.
When a topic repeats across lessons or videos, reuse existing cards rather than re-explaining from scratch.
Example:
The worktree card can appear in:
When reusing a card, adapt the framing to the current doc. Do not paste it blindly if the learner situation is different.
Optimize for:
learner understanding per minute
A good teaching doc:
Cut:
Prefer:
Here is the situation.
Here is what goes wrong.
Here is the concept that explains it.
Here is what to do.
Here is the demo.
Here is the rule to remember.
Before finalizing, check:
If the answer is no, revise before delivering.
## Different Terminals Are Not Different Workspaces
If you open two terminals in the same repo and run two Claude Code sessions, both agents are editing the same files.
That is the problem. One agent might be building the answer API while another redesigns the support page, but they are still writing into the same local folder on the same checked-out branch. When you run `git status`, their changes are mixed together.
```mermaid
flowchart LR
A["Terminal 1: Claude builds API"] --> C["Same repo folder"]
B["Terminal 2: Claude edits UI"] --> C
C --> D["Mixed working tree"]
D --> E["Hard-to-review diff"]
```
A git worktree fixes this by giving each session its own folder and branch:
```bash
git worktree add ../supportbot-answer-api -b answer-api
cd ../supportbot-answer-api
claude
```
> Demo: Open two terminals in the same repo, show that both report the same branch, then show `git worktree list` after creating a separate worktree.
**Takeaway:** a new terminal is not a new workspace. Use worktrees when multiple agents need to work at the same time.
Write compact, reusable teaching cards that make one idea click. Use when turning rough expertise, lesson sections, YouTube ideas, demos, or course material into clear teachable units.
Format Markdown for iA Writer. Minimal, prose-first, almost no bold or italic.
Turn a vague, messy, or multi-part user ask into a clean, self-contained prompt that a fresh agent could execute without further questions. Interview the user one question at a time — walking down the decision tree, branching on each answer — until the prompt is tight, then output the final prompt as the deliverable. Trigger eagerly: any voice-dictated input, filler-heavy prose, underspecified references ("the thing", "that script"), multi-part requests, or any plan the user wants stress-tested. The skill itself can be skipped for trivial one-line requests where producing a prompt artifact would be pure ceremony — but once invoked, always produce the prompt, even if execution looks trivial.
Create a beautiful HTML explanation of a repo, spec, PR, architecture, or concept so a smart beginner can understand and retell it.
Rewrite text to remove AI tells. Use when editing or reviewing writing that sounds like a chatbot wrote it. Detects and replaces inflated significance, rule-of-three, em dash overuse, AI vocabulary, condescending openers, reader-lecturing, signposting, and other tells.