Writing Your First Lesson

This tutorial walks you through writing a lesson and publishing it to the Skola marketplace.

A lesson is a Markdown file that teaches a concept, explains a workflow, or shares knowledge with the team. It lives under docs/ — either as a standalone file or grouped into a bundle (a subdirectory like docs/chapter-1/).

1. Decide: standalone or bundle?

	Standalone	Bundle
Use when	The topic stands on its own	The lesson is part of a series
Location	`docs/<lesson-name>.md`	`docs/<bundle-name>/<lesson-name>.md`
Extra frontmatter	—	`category` and `order`

If you're writing a one-off explainer (e.g. "how to write good prompts"), use a standalone lesson. If it's part of a course or chapter series, add it to the relevant bundle directory.

2. Scaffold the lesson

Run from the root of this repo:

# Standalone lesson → docs/my-lesson.md
skola create lesson my-lesson --output-dir docs

# Bundle lesson → docs/chapter-1/my-lesson.md
skola create lesson my-lesson --bundle chapter-1 --output-dir docs

For standalone lessons you'll be prompted for title and description (category is optional). For bundle lessons, category and order are required prompts. Skola creates the file with the frontmatter pre-filled.

3. Fill in the frontmatter

Every lesson uses the same template — the only difference for bundle lessons is filling in category and order:

---
title: "Your Lesson Title"
description: "One-line summary of what this lesson covers."
category: "Chapter 1: Agentic AI Fundamentals"  # leave empty for standalone lessons
order: 3                                          # leave empty for standalone lessons
author: your-github-username
contributors: []
---

category must match the bundle name exactly so lessons are grouped correctly
order controls the reading sequence within the bundle (1-based, no gaps)
contributors is optional — add GitHub usernames of people who helped

4. Write the content

Open your new file and replace the placeholder content. A good lesson:

Opens with the why — why does this topic matter?
Uses concrete examples — abstract advice is hard to act on
Keeps sections short — readers skim; make it easy to find what they need
Ends with a summary — one or two sentences per key takeaway

Use standard Markdown: headings, code blocks, tables, lists.

5. Review before publishing

Check the following before opening a PR:

[ ] Frontmatter is complete — no empty required fields
[ ] title and description are filled in (not template placeholders)
[ ] author is set to your GitHub username
[ ] For bundle lessons: category matches the bundle and order is correct
[ ] Content is not just the template boilerplate
[ ] At least one concrete example or code snippet is included

6. Publish to the marketplace

Use the Skola CLI to open a draft PR automatically:

# Standalone lesson
skola publish lesson docs/my-lesson.md

# Bundle (publishes all lessons in the folder as one PR)
skola publish lesson docs/chapter-1/

The CLI validates your frontmatter, injects your GitHub username as author, prompts for any missing category or order, and opens a draft PR to this repo.

If you don't have the Skola CLI, open a PR manually. The title should follow the pattern:

docs: add lesson "<your lesson title>"

Once merged, the lesson will be visible in the Skola docs and discoverable by anyone on the team.

Tips for great lessons

Do	Don't
Lead with the "why"	Start with a wall of definitions
Use real examples from our stack	Use generic placeholder examples
Keep each lesson focused on one topic	Try to cover everything in one file
Link to related skills or MCPs	Leave the reader with nowhere to go next
Use `order` to build on prior lessons	Write bundle lessons that assume random access

Author

@AgiMaulana-GDT View all contributors →