challenge-author - SKILL.md Agent Skill

name: challenge-author description: Write hands-on challenge lessons with verification allowed-tools: Read, Write, Edit, Glob, Grep

Challenge Author Skill

Purpose: Write hands-on challenge lessons with automated verification.

When to use: Workshop lesson requires learners to build something hands-on.

Prerequisites:

WORKSHOP-PLAN.md exists with challenge details
Skeleton lesson.adoc file exists
Previous concept lesson completed
Source course lessons identified

Overview

This skill writes challenge lessons that:

Guide learners through hands-on tasks (7-12 minutes)
Include automated verification (verify.cypher)
Provide solutions (solution.cypher)
Complete a building block transformation
Follow the Learn → Do → Verify pattern (this is the "Do")

Do NOT write concept lessons, quizzes, or practice lessons. This skill focuses ONLY on challenge lessons with verification.

Core Principle: Teaching Graph Databases

Focus on graph databases and graph technologies.

Build graph structures hands-on - Import nodes, create relationships, configure properties as graph-native activities
Use graph terminology - Nodes, relationships, properties (teach the graph model)
Make it fun and practical - Challenges should be engaging and build toward something that works
Deliver working results - Each challenge completes a building block that demonstrates value

Challenge lessons should:

Guide learners through hands-on graph building tasks
Reference graph concepts taught in previous lessons
Validate graph structure (node counts, relationship patterns)
Focus on what they're building, not what they're migrating from
Result in something that works and can be queried

Phase 1: Understand Challenge (5 min)

Checklist: Gather Information

Read WORKSHOP-PLAN.md for challenge objectives
Read source course lesson(s) identified
Read previous concept lesson (what was just taught)
Identify what learners will build/import/create
Note building block this challenge completes
Understand verification criteria (what to check)

Key Questions to Answer

Before writing anything, answer:

What will learners build? (e.g., import Product nodes, create relationships)
What was just taught? (previous concept lesson)
What building block does this complete? (e.g., "Products exist in graph" ✓)
How do we verify success? (what verify.cypher should check)
What data are they using? (CSV files, configuration)
What tools are they using? (Data Importer, Query tool, etc.)

Read These Files

MUST READ:
- WORKSHOP-PLAN.md (for challenge details)
- Source course lesson (for challenge content)
- Previous concept lesson (for context)
- CONTENT_GUIDELINES.md (for style rules)

REFERENCE:
- modules/2-foundation/lessons/4-import-products/ (example challenge)
- verify.cypher, solution.cypher, questions/verify.adoc examples

Phase 2: Plan Challenge Structure (10 min)

Checklist: Challenge Outline

Clear challenge statement upfront
Data table showing CSV structure
Download button for data files
Reference to tool mechanics (Module 1 Lesson 3)
Step-by-step instructions
Property configuration details
Snapshot option for skip-ahead
Verification criteria defined

Structure Template

Introduction
├── Challenge statement: "You will [action]"
└── Building block: "This completes [description]"

The Data
├── CSV structure table
└── Download button

Tool Reference
└── "See Module 1 Lesson 3 for tool mechanics"

Instructions
├── Step 1: [What to do]
├── Step 2: [What to do]
└── Step N: [What to do]

Configuration Details
└── Property mapping table

Snapshot Option
└── Collapsible with pre-built model

Verification
└── Include questions/verify.adoc

Building Block Marker

Every challenge MUST complete a building block. State it clearly:

This completes **Building Block 1**: "Products exist in the graph" ✓

Examples:

Module 2: "Products exist in the graph" ✓
Module 3: "Customer→Order path complete" ✓
Module 4: "Customer→Order→Product path complete" ✓

Phase 3: Write Challenge Introduction (5 min)

Checklist: Opening

Clear challenge statement
States what will be built
References building block completion
2-3 sentences max (concise!)

Opening Pattern

[.slide.discrete]
== Challenge

You will [specific action with tool].

This completes **Building Block [N]**: "[Description]" ✓

Example:

[.slide.discrete]
== Challenge

You will use Data Importer to import Product nodes from a CSV file.

This completes **Building Block 1**: "Products exist in the graph" ✓

Phase 4: Write Data Section (10 min)

Checklist: Data Information

Shows CSV structure in table format
Explains what each column represents
Uses [options="header"] AsciiDoc table
Download button with correct file path
Note about downloading once, using throughout

Data Table Pattern

[.slide]
== The Data

[Brief description of what the data represents]

[options="header"]
|===
| Column | Type | Description

| columnName1 | String | What this column contains
| columnName2 | Integer | What this column contains
| columnName3 | Float | What this column contains
|===

Example:

[.slide]
== The Data

The products.csv file contains information about items in the Northwind catalog.

[options="header"]
|===
| Column | Type | Description

| productId | String | Unique identifier for each product
| productName | String | Display name of the product
| unitPrice | Float | Price per unit in USD
| unitsInStock | Integer | Current inventory count
| categoryId | String | Reference to product category
|===

Download Button Pattern

[.slide]
== Load Data Files

button::Download Workshop Data[role=NX_DOWNLOAD_FILE, file="data/workshop-data.zip"]

**Note:** Download once and extract. You will use these CSV files throughout the workshop.

Phase 5: Write Instructions (15 min)

Checklist: Instructions Section

References Module 1 Lesson 3 for tool mechanics
Steps are numbered and clear
Focuses on WHAT to do, not HOW to click
Property configuration table included
Run import instructions included
Confirmation message stated

Tool Reference Pattern

CRITICAL: Do NOT repeat tool mechanics. Reference Module 1 Lesson 3.

[.slide]
== Using [Tool Name]

**Reference:** See Module 1 Lesson 3 for [tool name] mechanics.

**Steps for this challenge:**
1. [High-level step 1]
2. [High-level step 2]
3. [High-level step 3]

Example:

[.slide]
== Using Data Importer

**Reference:** See Module 1 Lesson 3 for Data Importer mechanics.

**Steps for this challenge:**
1. Open **Data Importer** from Aura console
2. Upload products.csv
3. Map to Product node
4. Configure properties
5. Run import

Property Configuration Pattern

[.slide]
== Configure Properties

Map the CSV columns to node properties:

[options="header"]
|===
| CSV Column | Type | Rename To | Notes

| productId | String | id | Unique identifier
| productName | String | name | Display name
| unitPrice | Float | | Keep original name
| unitsInStock | Integer | | Keep original name
|===

**Important:** Set `id` as the unique identifier property.

Run Import Pattern

[.slide]
== Run Import

Click **Run Import** to execute.

**Confirmation:** You should see "**77 Product nodes created**"

Phase 6: Write Snapshot Section (5 min)

Checklist: Snapshot Option

Uses [.collapsible] block
Title: "Load Pre-Built Data Model"
Explains what's included
Download button with snapshot file
Instructions for after loading

Snapshot Pattern

[.slide]
== Snapshot Option

[.collapsible]
.Load Pre-Built Data Model
====
**Skip ahead:** If you want to skip this challenge, load the pre-built model.

button::Download Snapshot[role=NX_DOWNLOAD_FILE, file="snapshots/module2-lesson4.zip"]

**What's included:**
* [What was built in this challenge]
* [Configuration details]

**After loading:**
1. Review the model in Data Importer
2. Connect to your instance
3. Click **Run Import**
====

Example:

[.slide]
== Snapshot Option

[.collapsible]
.Load Pre-Built Data Model
====
**Skip ahead:** If you want to skip this challenge, load the pre-built model.

button::Download Snapshot[role=NX_DOWNLOAD_FILE, file="snapshots/module2-lesson4.zip"]

**What's included:**
* Product node mapping
* Property configuration (id, name, unitPrice, unitsInStock)
* Ready to import 77 products

**After loading:**
1. Review the model in Data Importer
2. Upload products.csv
3. Click **Run Import**
====

Phase 7: Create Verification Files (20 min)

Checklist: Verification Files

verify.cypher returns outcome and reason
solution.cypher provides minimal passing code
questions/verify.adoc includes hint and solution
Verification checks are specific and helpful

File Structure

lesson-folder/
├── lesson.adoc
├── verify.cypher           (automated check)
├── solution.cypher         (minimal passing code)
└── questions/
    └── verify.adoc         (UI integration)

verify.cypher Pattern

CRITICAL: Must return exactly two columns: outcome (boolean) and reason (string)

// verify.cypher
RETURN COUNT { (:NodeLabel) } > 0 AS outcome,
       CASE
           WHEN COUNT { (:NodeLabel) } = 0
           THEN 'No [NodeLabel] nodes found. Check that you imported the data.'
           WHEN COUNT { (:NodeLabel) } < [expected]
           THEN 'Only ' + COUNT { (:NodeLabel) } + ' [NodeLabel] nodes found. Expected [expected].'
           ELSE 'Success! You imported ' + COUNT { (:NodeLabel) } + ' [NodeLabel] nodes.'
       END AS reason;

Example (verify.cypher):

// Verify Product nodes were imported
RETURN COUNT { (:Product) } > 0 AS outcome,
       CASE
           WHEN COUNT { (:Product) } = 0
           THEN 'No Product nodes found. Make sure you ran the import in Data Importer.'
           WHEN COUNT { (:Product) } < 77
           THEN 'Only ' + COUNT { (:Product) } + ' Product nodes found. Expected 77.'
           ELSE 'Success! You imported ' + COUNT { (:Product) } + ' Product nodes.'
       END AS reason;

solution.cypher Pattern

CRITICAL: Minimal code that passes verification, NOT full solution

// solution.cypher - minimal passing example
CREATE (:NodeLabel {id: "1", name: "Test Item"});

Example (solution.cypher):

// Minimal solution that passes verification
// This is NOT the recommended approach - use Data Importer instead
CREATE (:Product {id: "1", name: "Test Product"});
CREATE (:Product {id: "2", name: "Another Product"});

questions/verify.adoc Pattern

[.verify.slide]
== Validate Results

Once you have [completed the challenge/imported the data/created the relationships], verify your results.

verify::[]

[TIP,role=hint]
.Hint
====
[Guidance toward solution without giving it away]

**Check:**
* [Thing to verify 1]
* [Thing to verify 2]
====

[TIP,role=solution]
.Solution
====
[Manual validation query]

[source,cypher]
.Check imported nodes
----
MATCH (n:NodeLabel)
RETURN count(n) AS total;
----

You should see [expected result].

**If verification fails:**
* [Troubleshooting step 1]
* [Troubleshooting step 2]
====

Example (questions/verify.adoc):

[.verify.slide]
== Validate Results

Once you have imported Product nodes, verify your results.

verify::[]

[TIP,role=hint]
.Hint
====
Make sure you completed all steps in Data Importer:

**Check:**
* CSV file uploaded
* Product node mapped
* Properties configured (id, name, unitPrice, unitsInStock)
* Import executed successfully
====

[TIP,role=solution]
.Solution
====
Run this query to check your Product nodes:

[source,cypher]
.Check Product nodes
----
MATCH (p:Product)
RETURN count(p) AS total,
       collect(p.name)[0..5] AS sampleNames;
----

You should see 77 total products with names like "Chai", "Chang", "Aniseed Syrup".

**If verification fails:**
* Verify the CSV file was uploaded correctly
* Check that property names match (id, name not productId, productName)
* Ensure you clicked "Run Import"
* Try reloading the Data Importer page
====

Phase 8: Write Summary (5 min)

Checklist: Summary Section

Lists what was accomplished
States number of nodes/relationships created
Notes properties configured
Confirms building block completion with ✓
Forward reference to next lesson

Summary Pattern

[.summary]
== Summary

You imported [Entity] nodes:

* [N] nodes created
* Properties: [list properties]
* **Building Block [N]**: "[Description]" ✓

In the next lesson, you will [what comes next].

Example:

[.summary]
== Summary

You imported Product nodes using Data Importer:

* 77 Product nodes created
* Properties: id, name, unitPrice, unitsInStock
* **Building Block 1**: "Products exist in the graph" ✓

In the next lesson, you will write queries to explore the products you imported.

Phase 9: Apply Style Rules (10 min)

Checklist: Technical Requirements

Two line breaks between ALL sections
[.slide.discrete] for introduction
[.slide] for main sections
[.summary] for summary
Include questions/verify.adoc with leveloffset
All tables use [options="header"] AsciiDoc format
No tool mechanics (references Module 1 Lesson 3 instead)
Building block completion marker present
Natural tone (no sales/AI language)
CRITICAL: Blank line before ALL lists (after text, headers, bold text)
CRITICAL: Code callouts use angle brackets // <1> not // (1)

Include Verification

At the end of instructions, before summary:

include::questions/verify.adoc[leveloffset=+1]


[.summary]
== Summary

Phase 10: Review and Refine (10 min)

Checklist: Self-Review

Re-read lesson aloud
Check timing (7-12 minutes to complete)
Verify clear challenge statement
All tables are AsciiDoc format
References Module 1 Lesson 3 for tool mechanics
Snapshot option present
verify.cypher returns outcome + reason
solution.cypher is minimal
questions/verify.adoc has hint + solution
Building block completion stated
Summary includes forward reference

Test Verification Files

Before completing:

Test verify.cypher:
- Returns outcome (boolean) and reason (string)?
- Handles zero results case?
- Handles partial results case?
- Provides helpful error messages?
Test solution.cypher:
- Runs without errors?
- Passes verify.cypher check?
- Is minimal (not full solution)?
Test questions/verify.adoc:
- Hint guides without giving answer?
- Solution provides manual validation query?
- Troubleshooting steps are helpful?

Examples and References

Example Challenge Lessons

See these real files:

modules/2-foundation/lessons/4-import-products/
- Files: lesson.adoc, verify.cypher, solution.cypher, questions/verify.adoc
- Demonstrates: Data table, property configuration, snapshot, verification
modules/3-modeling-relationships/lessons/2-import-customers-orders/
- Demonstrates: Multiple entity imports, relationship creation
modules/4-many-to-many/lessons/2-create-orders-relationships/
- Demonstrates: Many-to-many relationship challenge

What These Files Demonstrate

4-import-products/lesson.adoc:

Clear challenge statement upfront
Data table with CSV structure
Download button for workshop data
Reference to Module 1 Lesson 3 (no repeated mechanics)
Property configuration table
Collapsible snapshot section
Includes questions/verify.adoc
Building block marker: "Building Block 1: 'Products exist' ✓"

verify.cypher:

Returns outcome and reason
Uses COUNT subquery: COUNT {(:Product)} > 0
Provides helpful error messages for different scenarios

solution.cypher:

Minimal code: CREATE (:Product {id: "1", name: "Test"})
Just enough to pass, not full solution

questions/verify.adoc:

[.verify.slide] marker
verify::[] macro for system integration
Hint section with checklist
Solution with manual validation query
Troubleshooting steps

Output Checklist

Before marking challenge complete, verify:

File: lesson.adoc exists
File: verify.cypher exists and tested
File: solution.cypher exists and tested
File: questions/verify.adoc exists
Metadata: :type: challenge, :order: X, :duration: 7-12
Source attribution in comments
Clear challenge statement with building block
Data table with CSV structure
Download button for data files
References Module 1 Lesson 3 (not repeating mechanics)
Property configuration details
Snapshot option with collapsible
Verification files all working
Summary with building block ✓ marker
Two line breaks between sections
No markdown, only AsciiDoc

References

CONTENT_GUIDELINES.md - Verification patterns
HOW-TO-BUILD-WORKSHOPS.md - Challenge methodology
create-new-workshop.mdc - Challenge requirements
modules/2-foundation/lessons/4-import-products/ - Complete example