Writing a Cloudflare Dev School course

A course is a short series of exercises that a student’s AI coding agent teaches them, one conversation at a time. It’s plain Markdown, hosted wherever you like. Students start it by telling their agent “take the course at” and its URL, and their progress counts on Cloudflare Dev School, the same as for the built-in courses.

Where to host it

• A public git repo, for any course: COURSE.md at the root, and one Markdown file per exercise in exercises/. Students’ agents clone it.
• A single Markdown file at any https URL, for a smaller course: a COURSE.md whose ## sections are its exercises.

Private repos, and courses in a subdirectory of a repo, aren’t supported yet.

COURSE.md

---
name: durable-objects
description: "Build stateful apps on Cloudflare with Durable Objects, for developers who've deployed a Worker."
metadata:
  author: Your name
  url: https://github.com/you/durable-objects-course
---

# Durable Objects

What the course covers and who it's for, in a paragraph or two.

• name: lowercase letters, numbers, and single hyphens, at most 64 characters.
• description: what the course teaches and who it’s for, at most 1,024 characters.
• metadata.author: optional, shown to students.
• metadata.url: optional. Students’ progress is keyed by the course’s URL, so set this if the course might move or get linked to in more than one way. Otherwise it’s the URL the student gave their agent.
• license and compatibility (prerequisites): optional, like in an Agent Skill’s SKILL.md.
• Then a # Title and an introduction.

Exercises

In a repo, each exercise is a file in exercises/:

durable-objects-course/
├── COURSE.md
└── exercises/
    ├── 00-interview.md      optional
    ├── 01-first-object.md
    └── 02-websockets.md

• Order: natural filename order, so 2-alarms.md comes before 10-cleanup.md.
• Slug: the filename without .md or its number prefix, so 01-first-object.md is first-object. Renumbering files to insert an exercise doesn’t change slugs, so students keep their progress. Slugs follow the same rules as name.
• Title: the file’s first # heading.
• Frontmatter is optional: a one-line description, and agent-instructions, which only the student’s agent reads.

---
description: "Create a Durable Object and call it from a Worker."
agent-instructions: |
  Help the student add a counter Durable Object to their Worker and
  deploy it. Before marking this exercise complete, fetch the deployed
  URL twice yourself and check the count went up.
---

# Your first object

What the student will build and why, written for the student.

In a single file, each ## section of COURSE.md is an exercise, in order. Its title is the heading’s text and its slug is the heading’s GitHub-style anchor, so ## Your first object is your-first-object. There’s no frontmatter per exercise, so address any notes for the agent in the section itself.

---
name: kv-in-ten-minutes
description: "Store and read data with Workers KV, for developers who've deployed a Worker."
---

# KV in ten minutes

An introduction.

## Create a namespace

...

## Read it back

...

The interview

Every course starts with an interview, so the student’s agent can pitch the course at the right level. To write your own, add an exercise with the slug interview (00-interview.md, or a ## Interview section). It always comes first, whatever its filename.

• Ask at most four short questions. Claude Code’s question tool takes four at a time.
• Write them as plain prose, like a list. There’s no question format, only the agent reads them.
• Don’t ask what Dev School’s Agent setup interview already covers: experience with AI agents, where the student has deployed before, what they want to build, and whether they want quizzes.
• Interviews are never quizzed.

Leave it out and Dev School’s default interview has the agent write two to four questions from your course’s content.

Make every exercise checkable

An exercise is complete when the student’s agent says so, so give the agent something concrete to check first: fetch a deployed URL and compare the response, run a command and read its output, or look at a file the student changed. Say what the check is in agent-instructions. Students who opted in also get a short quiz after each exercise, which their agent writes from the exercise.

Examples

The built-in courses use the same format:

• Agent setup’s COURSE.md and its interview
• Workers basics’ COURSE.md and “Deploy a Worker”, which checks the deployed URL before completing