overview-author - SKILL.md Agent Skill

name: overview-author description: Write workshop and module overviews allowed-tools: Read, Write, Edit, Glob, Grep

Overview Author Skill

Purpose: Write workshop and module overview lessons.

When to use: Workshop needs an overview lesson (always first lesson) or module needs an overview (module.adoc).

Prerequisites:

WORKSHOP-PLAN.md exists with workshop/module details
Understanding of workshop goal and outcomes
Knowledge of module structure

Overview

This skill writes overview lessons for:

Workshop overviews - First lesson of every workshop (Module 1, Lesson 1)
Module overviews - Introduction to each module (module.adoc)

Do NOT write concept lessons, challenges, or practice lessons. This skill focuses ONLY on overviews.

Core Principle: Teaching Graph Databases

Focus on graph databases and graph technologies.

Lead with what they'll build - Show the concrete deliverable and its value
Use comparisons when helpful - SQL or other tech comparisons can provide context for the final solution
Be factual about value - Performance in plain language (index lookup then pointer traversal; cost scales with connections, not table size), simplicity, readability—stick to facts, not sales language. Do not use Big O or notation like O(1), O(k), O(n×m).
Make it sound fun and achievable - 2 hours to build something that works and demonstrates value

Workshop overview pattern:

Start with the concrete goal (what they'll build)
Explain why it matters (business value, real-world use case)
Use comparisons if they help demonstrate value (e.g., final solution: 11 lines vs 38 lines)
Focus on the hands-on journey and working deliverable

Part A: Workshop Overview Lessons

Phase 1: Understand Workshop Goal (10 min)

Checklist: Gather Information

Read WORKSHOP-PLAN.md for workshop goals
Identify concrete deliverable
List all modules and their building blocks
Note prerequisites
Determine duration (core + optional)
Understand value proposition

Key Questions to Answer

Before writing anything, answer:

What will learners build? (concrete end deliverable)
Why does it matter? (value proposition, business benefit)
What are the modules? (list with building blocks)
Who is this for? (target audience, prerequisites)
How long will it take? (core path + optional)
What's the progression? (how modules build on each other)

Read These Files

MUST READ:
- WORKSHOP-PLAN.md (for workshop structure)
- CONTENT_GUIDELINES.md (for style rules)
- HOW-TO-BUILD-WORKSHOPS.md (for methodology)

REFERENCE:
- modules/1-aura-setup/lessons/1-workshop-overview/lesson.adoc

Phase 2: Plan Workshop Overview Structure (10 min)

Checklist: Overview Outline

THE GOAL stated upfront
What will be built
Module-by-module progression
Prerequisites clearly listed
Duration expectations set
Value proposition motivated

Workshop Overview Structure

Introduction
└── States THE GOAL immediately

What You'll Build
├── Concrete deliverable
└── What it demonstrates

Module Progression
├── Module 1: [Transformation]
├── Module 2: [Transformation]
├── Module 3: [Transformation]
└── Module N: [Final integration]

Prerequisites
└── Required knowledge/tools

Duration
├── Core path: X hours
└── With optional: Y hours

Why This Matters
└── Value proposition (factual, not sales)

Summary
└── Call to action: "Ready? Let's go →"

Phase 3: Write Workshop Overview Content (30 min)

Checklist: Content Sections

Opening states THE GOAL immediately
Shows what will be built
Module-by-module outline
Prerequisites clear
Duration stated
Motivates with value (factual, not sales)
Ends with "let's go" button

Workshop Overview Pattern

= Workshop Overview: [What They'll Build]
:type: lesson
:order: 1

// Source: Adapted from [course-name]/[lesson]


[.slide.discrete]
== Introduction

In this workshop, you will [concrete action and deliverable].


[.slide]
== The Goal

By the end of this workshop, you will have built [concrete deliverable].

[Explain what this demonstrates or enables]


[.slide]
== What You'll Learn

This workshop guides you through [X] modules:

**Module 1: [Name]**
* [What you'll do]
* [Building block completion]

**Module 2: [Name]**
* [What you'll do]
* [Building block completion]

**Module 3: [Name]**
* [What you'll do]
* [Building block completion]

**Module N: [Name]**
* [What you'll do]
* [Building block completion]


[.slide]
== Prerequisites

To complete this workshop, you should have:

* [Prerequisite 1]
* [Prerequisite 2]
* [Prerequisite 3]

**Tools needed:**
* [Tool 1] - [Why]
* [Tool 2] - [Why]


[.slide]
== Duration

**Core path:** [X] hours
* All required lessons
* Essential concepts and challenges

**With optional lessons:** [Y] hours
* Additional practice exercises
* Deeper exploration of concepts

**Pace yourself:**
* Take breaks between modules
* Optional lessons can be completed as homework


[.slide]
== Why [This Approach]?

[Factual value proposition - NOT sales language]

[Specific benefits:]
* [Benefit 1 with concrete example]
* [Benefit 2 with concrete example]
* [Benefit 3 with concrete example]


[.summary]
== Summary

In this workshop, you will:

* [Outcome 1]
* [Outcome 2]
* [Outcome 3]

**Time commitment:** [X] hours core, [Y] hours with optional lessons

Ready to get started?

read::Let's go![]

Example Workshop Overview

= Workshop Overview: Import and Query the Northwind Dataset
:type: lesson
:order: 1

// Source: Adapted from modeling-fundamentals and importing-fundamentals


[.slide.discrete]
== Introduction

In this workshop, you will import a business dataset into a graph database and build queries to answer business questions.


[.slide]
== The Goal

By the end of this workshop, you will have built **a complete recommendation query** that finds similar customers and suggests products they might like.

This demonstrates how graph databases excel at connected data queries that would require complex JOINs in SQL.


[.slide]
== What You'll Learn

This workshop guides you through 5 modules:

**Module 1: Aura Setup**
* Create a free Neo4j Aura instance
* Understand the tools you'll use
* Prepare your environment

**Module 2: Building Your Graph**
* Model business data as nodes and relationships
* Import products using Data Importer
* Query your graph with Cypher

**Module 3: Basic Relationships**
* Import customers and orders
* Create relationships between entities
* Traverse the Customer → Order path

**Module 4: Many-to-Many Relationships**
* Model order line items
* Create the full Customer → Order → Product path
* Write multi-hop traversal queries

**Module 5: Building Recommendations**
* Find similar customers
* Use collaborative filtering patterns
* Build the complete recommendation query


[.slide]
== Prerequisites

To complete this workshop, you should have:

* Basic understanding of databases (SQL helpful but not required)
* Familiarity with CSV files and data structures
* Comfort with reading and modifying query syntax

**Tools needed:**
* **Web browser** - Chrome, Firefox, or Safari
* **Neo4j Aura Free account** - We'll create this in Module 1


[.slide]
== Duration

**Core path:** 2 hours
* All required lessons
* Essential modeling, importing, and querying

**With optional lessons:** 3 hours
* Additional query practice
* Deeper exploration of patterns

**Pace yourself:**
* Each module takes 20-30 minutes
* Take breaks between modules
* Optional lessons can be completed as homework


[.slide]
== Why Graphs for Connected Data?

Graph databases are well-suited for connected data because relationships are stored as first-class citizens with direct pointers, not foreign keys requiring table scans.

**Concrete advantages:**
* **Simpler queries** - No JOIN operations for relationship traversals
* **Predictable performance** - Cost scales with connections traversed, not table sizes; graph stores adjacency so traversals follow pointers instead of repeated index scans and joins
* **Natural modeling** - Queries read like the questions you're asking

**Example:** Finding "what products did this customer buy" requires 3 JOINs in SQL (4 tables) vs a simple 2-hop traversal in Cypher.


[.summary]
== Summary

In this workshop, you will:

* Model business data as a graph
* Import CSV files using Data Importer
* Write Cypher queries to answer business questions
* Build a recommendation query using collaborative filtering

**Time commitment:** 2 hours core path, 3 hours with optional practice

Ready to get started?

read::Let's go![]

Part B: Module Overviews

Phase 1: Understand Module Purpose (5 min)

Checklist: Module Information

Read WORKSHOP-PLAN.md for module objectives
Identify building block this module completes
List lessons in this module
Note what was completed in previous module
Understand what comes after this module

Key Questions to Answer

Before writing anything, answer:

What does this module accomplish? (building block)
What was just completed? (previous module)
How many lessons? (count and types)
What will learners be able to do? (outcomes)
How long will it take? (duration)

Phase 2: Write Module Overview (15 min)

Checklist: Module Overview Content

Clear module title with order
Brief description of accomplishment
"By the end of this module" bullet list
Link to first lesson with styled button

Module Overview Pattern

= [Module Title]
:order: N

[Brief description of what this module accomplishes - 1-2 sentences]


By the end of this module, you will:

* [Outcome 1]
* [Outcome 2]
* [Outcome 3]


link:./1-first-lesson/[Ready? Let's go →, role=btn]

Example Module Overview 1

= Aura Setup
:order: 1

In this module, you will create a free Neo4j Aura instance and familiarize yourself with the tools you'll use throughout the workshop.


By the end of this module, you will:

* Understand what Neo4j Aura is and how it works
* Have a running Aura Free instance
* Know how to use Data Importer and Query tools
* Be ready to import your first dataset


link:./1-workshop-overview/[Ready? Let's go →, role=btn]

Example Module Overview 2

= Building Your Graph
:order: 2

In this module, you will learn graph fundamentals and import your first dataset using Data Importer.


By the end of this module, you will:

* Understand nodes, relationships, and properties
* Know basic Cypher syntax for reading data
* Have Product nodes imported into your graph
* Be able to query products with simple patterns


link:./1-graph-elements/[Ready? Let's go →, role=btn]

Example Module Overview 3

= Many-to-Many Relationships
:order: 4

In this module, you will model the many-to-many relationship between orders and products, completing the full Customer → Order → Product path.


By the end of this module, you will:

* Understand how graphs eliminate pivot tables
* Create ORDERS relationships between Order and Product nodes
* Write multi-hop traversal queries
* Compare graph queries to their SQL equivalents


link:./1-graph-vs-pivot-tables/[Ready? Let's go →, role=btn]

Phase 3: Apply Style Rules (5 min)

Checklist: Technical Requirements

Two line breaks between sections
Module title is clear and descriptive
Order attribute is correct
Outcomes are bulleted
Link uses role=btn styling
No markdown, only AsciiDoc
Natural tone (no sales language)

Module Overview Requirements

Metadata:

= Module Title
:order: N

Structure:

Brief description (1-2 sentences)
"By the end of this module, you will:" + bullets
Link to first lesson with role=btn
CRITICAL: Blank line before the bullet list

Style:

Sentence case titles
Active voice ("you will", not "you'll")
Concrete outcomes (not vague)
Forward-looking (what they'll accomplish)

Phase 4: Review and Refine (5 min)

Checklist: Self-Review

Re-read overview aloud
THE GOAL is clear (workshop overview only)
Outcomes are specific and concrete
Prerequisites are accurate
Duration is realistic
Value proposition is factual (not sales)
Link points to correct first lesson
Two line breaks between sections
Natural, friendly tone

Common Issues to Fix

Issue: Vague outcomes

❌ "Learn about graphs"
✅ "Model business data as nodes and relationships"

Issue: Sales language

❌ "Powerful graph capabilities that will transform your queries"
✅ "Graph traversal follows pointers in memory; cost scales with connections traversed, not table sizes—unlike SQL JOINs which repeatedly scan indexes and materialize joins"

Issue: Missing prerequisites

❌ "Anyone can take this workshop"
✅ "Basic understanding of databases, familiarity with CSV files"

Issue: Unrealistic duration

❌ "Complete in 30 minutes"
✅ "2 hours core path, 3 hours with optional lessons"

Examples and References

Example Workshop Overview

See this real file:

modules/1-aura-setup/lessons/1-workshop-overview/lesson.adoc
- Demonstrates: THE GOAL upfront, module progression, prerequisites, duration, value proposition

Example Module Overviews

See these real files:

modules/2-building-your-graph/module.adoc
modules/3-modeling-relationships/module.adoc
modules/4-many-to-many/module.adoc
modules/5-final-review/module.adoc

What These Files Demonstrate

Workshop overview (1-workshop-overview/lesson.adoc):

Introduces THE GOAL immediately
Shows what will be built
Module-by-module progression outline
Prerequisites clearly stated
Duration expectations set (2 hours core, 3 with optional)
Motivates with factual value proposition (not sales)

Module overviews (module.adoc files):

Clear module title and order
Brief description of accomplishment
"By the end of this module, you will:" bullet list
Link to first lesson with styled button

Key patterns:

Concrete outcomes (not vague)
Forward-looking (what they'll accomplish)
Sentence case titles
Natural tone (no sales language)
Two line breaks between sections

Output Checklist

Workshop Overview Checklist

Before marking workshop overview complete, verify:

File: lesson.adoc in first lesson folder
Metadata: :type: lesson, :order: 1
THE GOAL stated in opening
What will be built section
Module-by-module progression
Prerequisites section
Duration section (core + optional)
Value proposition (factual, not sales)
Summary with outcomes
"Let's go" button
Two line breaks between sections
No markdown, only AsciiDoc

Module Overview Checklist

Before marking module overview complete, verify:

File: module.adoc in module folder
Metadata: :order: N
Clear module title
Brief description (1-2 sentences)
"By the end of this module" section
3-5 concrete outcomes
Link to first lesson with role=btn
Two line breaks between sections
No markdown, only AsciiDoc

References

CONTENT_GUIDELINES.md - Style guide
HOW-TO-BUILD-WORKSHOPS.md - Overview methodology
create-new-workshop.mdc - Workshop overview requirements
modules/1-aura-setup/lessons/1-workshop-overview/ - Complete workshop overview example
modules/4-many-to-many/module.adoc - Module overview example