Lesson Runner Skill

Standard patterns for running lesson code in the agent-spike multi-agent learning project.

When to Use

This skill activates when:

• User wants to run test/demo scripts in lessons
• User wants to execute lesson CLI commands
• User is working in lessons/ directories
• User asks "how to run this lesson"

Running Lesson Code

Standard Execution Patterns

Navigate to lesson directory first:

cd lessons/lesson-XXX

Run test scripts:

uv run python test_router.py
uv run python test_coordinator.py
uv run python test_*.py

Run demo scripts:

uv run python demo.py "https://example.com"
uv run python demo.py "https://youtube.com/watch?v=..."

Run module CLI (if lesson has one):

# Interactive mode
uv run python -m youtube_agent.cli interactive
uv run python -m webpage_agent.cli interactive

# Analyze mode
uv run python -m youtube_agent.cli analyze "URL"
uv run python -m <name>_agent.cli analyze "URL"

Running from Project Root

You can also run from project root (uv finds the lesson automatically):

# From root directory
uv run python lessons/lesson-003/demo.py "URL"
uv run python lessons/lesson-001/test_agent.py

Why uv run Works

Cross-directory execution:

1. uv

   searches upward for

   pyproject.toml

   (finds project root)
2. Looks for

   .venv

   at project root
3. Also checks for lesson-specific

   .venv

   if in lesson directory
4. Runs command with correct Python interpreter and dependencies

Benefits:

• No manual venv activation
• No manual path management
• Works from any directory
• Cross-platform (Windows/Linux/Mac)

Virtual Environment Structure (FYI)

This project has a hybrid .venv structure:

• Root .venv: Contains all dependencies (created by

  uv sync --all-groups

  )
• Lesson-001 .venv: Legacy from initial setup (still works)
• Lessons 002, 003: Use shared root .venv

You don't need to manage this -

uv run python

handles it automatically.

Common Commands

# Install lesson dependencies
uv sync --group lesson-001
uv sync --group lesson-002
uv sync --group lesson-003
uv sync --all-groups              # Install all lessons (recommended)

# Check what's installed
uv pip list

# Run specific lesson
cd lessons/lesson-001
uv run python -m youtube_agent.cli analyze "https://youtube.com/watch?v=..."

cd lessons/lesson-002
uv run python -m webpage_agent.cli analyze "https://github.com/..."

cd lessons/lesson-003
uv run python test_coordinator.py

Troubleshooting

If you get "module not found" errors:

1. Check dependencies installed:

   uv sync --group lesson-XXX

2. Verify you're using

   uv run python

   (not

   python

   directly)
3. Check that you're in the right lesson directory

If you get ".env not found" warnings:

1. Copy

   .env

   from another lesson:

   cp ../lesson-001/.env .

2. Or create new

   .env

   with API keys (see lesson README)

If tests fail:

1. Check STATUS.md for known issues
2. Verify API keys in

   .env

3. Check that lesson is marked as complete in STATUS.md

Quick Reference

Most common pattern:

cd lessons/lesson-XXX
uv run python <script>.py

Always use:

• ✅

  uv run python

  (handles venv automatically)
• ✅

  -m

  flag for module execution (e.g.,

  -m youtube_agent.cli

  )
• ✅ Navigate to lesson directory first (clearer context)

Never use:

• ❌ Manual .venv paths (

  .venv/Scripts/python.exe

  )
• ❌ System

  python

  command directly
• ❌ Relative venv paths (

  ../../../.venv/

  )

---

Note: See python-workflow skill for general Python/uv best practices. This skill is specific to running agent-spike lesson code.