This guide walks you through creating a new workshop from idea to pull request. Before you begin, complete the Getting Started setup (Git, Hugo, fork) and read the Site Architecture overview.

Our philosophy

Nuevo Foundation workshops should feel like guided adventures, not textbooks. Every workshop tells a story that students follow at their own pace. The best workshops are:

Learn from our best workshops

Study these gold-standard workshops before building your own:

Web basics (HTML/CSS) — content/english/web-basics/

Python turtle — content/english/python-turtle/

EarSketch (Python and JS blocks) — content/english/python-earsketch/

Create a workshop with Copilot

This repository includes the workshop-builder skill for GitHub Copilot CLI. The skill reads these guidelines, studies a relevant existing workshop, uses the scaffold script, writes the content, and runs the publication checks.

Start Copilot CLI from the repository root:

copilot

If the skill was added while Copilot was already running, reload project skills:

/skills reload

Confirm that Copilot discovered it:

/skills info workshop-builder

Then include the skill name and workshop brief in the prompt:

Use the /workshop-builder skill to create a 45-minute beginner Python
workshop for ages 10–13. It should run in the browser and teach variables,
input, and if statements through a robot rescue story.

The skill uses a standard questionnaire to collect the title, age range, duration, previous coding experience, learning outcomes, coding language, in-person or virtual delivery format, number of activities, story, and special requirements. It asks for all missing information together before creating files. If the requested activity count is likely to exceed the available time, the skill warns about the estimate but keeps the user’s requested count.

Copilot may also select the skill automatically when the request clearly asks to create, revise, or review a Nuevo Foundation workshop.

Step 1: scaffold your workshop

Use the scaffold script to generate the correct directory structure and template files. Do not create workshop files manually — the scaffold ensures correct Hugo frontmatter, file naming, and directory layout.

Requirement: Python 3.7 or later. Verify with python --version (or python3 --version on macOS/Linux).

Run this from the root of the workshops repository:

python tools/new-workshop.py --name "my-workshop" --title "My Workshop" \
  --coding-language python --topics programming-basics

Use --dry-run first to preview what would be created without writing any files:

python tools/new-workshop.py --name "my-workshop" --title "My Workshop" \
  --coding-language python --topics programming-basics --dry-run

This generates the standard starter structure:

content/english/my-workshop/
├── _index.md          ← Landing page (intro, prerequisites, TOC)
├── activity-1.md      ← First activity
├── activity-2.md      ← Second activity
├── activity-3.md      ← Third activity
├── answer-key.md      ← Answer key (hidden from navigation)
└── media/
    └── .gitkeep       ← Folder for screenshots and images

Scaffold options

OptionDefaultDescription
--name(required)Directory name in kebab-case (e.g. python-web-scraping)
--title(required)Display title (e.g. "Python: Web Scraping")
--activities or -n3Number of activity files to generate (1 to 25)
--difficultybeginnerbeginner, intermediate, or advanced
--coding-language(required)Canonical coding-language tag from data/taxonomy.yaml
--topics(required)One or more canonical topic tags from data/taxonomy.yaml
--description(empty)Short description for the landing page
--prereq"None"Prerequisite workshop name
--iconfas fa-codeFont Awesome icon class
--language or -lenglishLanguage folder (e.g. espanol, korean)
--no-answer-key(off)Skip generating the answer key file
--dry-run(off)Preview without writing files

Example: intermediate workshop with 5 activities

python tools/new-workshop.py \
  --name "python-web-scraping" \
  --title "Python: Web Scraping" \
  --activities 5 \
  --difficulty intermediate \
  --coding-language python \
  --topics data \
  --prereq "Python Basics" \
  --description "Learn to scrape data from websites using Python"

Step 2: fill in your content

Open the generated files and replace the placeholder text:

  1. _index.md (landing page): Write the introduction. Set up your story, explain what students will learn, and list prerequisites. The `

shortcode at the bottom auto-generates the table of contents — leave it in place. 2. **activity-N.md** files: Write step-by-step instructions for each activity. Replace placeholder titles with descriptive names (e.g. “Activity 1: Drawing shapes”). Include a challenge at the end of each activity. 3. **answer-key.md**: Add solutions for every activity challenge. This file has hidden: true in its frontmatter so it won't appear in navigation. 4. **media/**: Add screenshots, diagrams, or images. Use media/image-name.pngin_index.mdand../media/image-name.pngin activity pages (activity pages render one level deeper in Hugo, so they need../` to reach the media folder).

For formatting help, see the Formatting and Code and interactivity guides.

Step 3: preview locally

From the workshops directory:

hugo server -D

Open http://localhost:1313/ and navigate to your workshop. Click through every activity to check that content renders correctly, images load, and navigation works.

Step 4: open a pull request

git checkout -b workshop/my-workshop
git add content/english/my-workshop/
git commit -m "Add my-workshop workshop"
git push --set-upstream origin workshop/my-workshop

Then open a pull request from your fork to the main repo.

Workshop quality checklist

Use this checklist before submitting your PR. Reviewers will check the same items.

Landing page (_index.md)

` shortcode present at bottom for auto-generated table of contents

Activities (activity-N.md)

Answer key (answer-key.md)

Media and assets

Writing and language

Hugo and build

PR review checklist (for reviewers)

When reviewing a workshop PR:

  1. Does it actually run? Follow the instructions yourself. Can a student get working code?
  2. Answer key complete? Map every activity’s challenge to its answer
  3. Images load? Check for case-sensitivity issues
  4. Language quality? Read for typos, grammar, and accuracy
  5. Self-paced friendly? Could a student complete this without a teacher?
  6. Fun factor? Is the theme engaging? Can students personalize it?
  7. Accessibility? Descriptive alt text on all images, clear instructions
  8. Progressive difficulty? Activities build on each other, one concept at a time
  9. Hugo build clean? Run hugo server -D and check for warnings
  10. Walk through it yourself. Complete the workshop as a student would, start to finish

The Hugo theme automatically adds a Nuvi “You did it! Workshop complete” celebration to the last page of every workshop. You do not need to create a separate conclusion file. If your workshop has a special story ending, you can optionally add a conclusion.md page.

Resources