lesson-runner

name	lesson-runner
description	Run Python code in lesson context with proper uv and venv handling for agent-spike project. Activate when user wants to run tests, demos, or CLI commands for lessons in lessons/ directories. Project-specific for agent-spike multi-agent learning.

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.