Skill: dncolomer/open-lesson (version 1.0.2)

# openLesson Agent API Skill You are an AI agent that can interact with the openLesson tutoring platform via API. ## Overview openLesson is a tutoring system that uses audio-based dialogue to help users learn by asking questions rather than giving answers. The platform generates personalized learning plans as directed graphs, where each node is a session. Agents can programmatically generate learning plans, start sessions, and analyze audio chunks for reasoning gaps. ## Important: No Browser Tool Required You do not need a browser tool. You only need shell tools (e.g., curl) to make API calls to openLesson. ## Important: Audio-Only System **CRITICAL**: The openLesson platform is **audio-only**. The analyze endpoint accepts ONLY audio input, NOT text. - Always convert speech to base64-encoded audio before calling the analyze endpoint - Supported formats: webm, mp4, ogg - Do not send text to the analyze endpoint - it will be rejected ## Authentication Include your API key in the Authorization header: ``` [REDACTED_SECRET] ``` **Important**: Always use `https://www.openlesson.academy` for API calls. The domain `openlesson.academy` has a redirect that loses the Authorization header. API keys can be generated from the user's dashboard at `/dashboard`. ## Credentials This skill requires an API key for the openLesson API: - **Environment variable**: `OPENLESSON_API_KEY` - **How to obtain**: Generate from the user's dashboard at `/dashboard` - **No calendar access needed**: The skill does NOT create actual calendar events. "Reminders" means the agent proactively notifies the human when a session is due — this is behavioral, not a technical integration. ## Session State Session IDs are stored in-memory for the duration of the conversation. No persistent storage is used or required. ## Bash Command Patterns When running API calls as shell commands, use this pattern to avoid JSON escaping issues: ### Basic POST with JSON body ```bash bash -c 'printf "{\"topic\":\"Quantum Computing\",\"days\":60}" | curl -X POST "https://www.openlesson.academy/api/agent/plan" -H "Authorization: Bearer $OPENLESSON_API_KEY" -H "Content-Type: application/json" --data-binary @-' ``` ### With variables ```bash TOPIC="Quantum Computing" DAYS=60 bash -c "printf '{\"topic\":\"$TOPIC\",\"days\":$DAYS}' | curl -X POST 'https://www.openlesson.academy/api/agent/plan' -H 'Authorization: Bearer $OPENLESSON_API_KEY' -H 'Content-Type: application/json' --data-binary @-" ``` ### Start session ```bash bash -c 'printf "{\"plan_node_id\":\"NODE_UUID\",\"problem\":\"Explain neural networks\"}" | curl -X POST "https://www.openlesson.academy/api/agent/session/start" -H "Authorization: Bearer $OPENLESSON_API_KEY" -H "Content-Type: application/json" --data-binary @-' ``` ### Analyze audio ```bash bash -c 'printf "{\"session_id\":\"SESSION_UUID\",\"audio_base64\":\"BASE64_DATA\",\"audio_format\":\"webm\"}" | curl -X POST "https://www.openlesson.academy/api/agent/session/analyze" -H "Authorization: Bearer $OPENLESSON_API_KEY" -H "Content-Type: application/json" --data-binary @-' ``` ## Endpoints ### 1. Generate Learning Plan Creates a directed graph of learning sessions for a given topic. **Endpoint**: `POST /api/agent/plan` **Request**: ```json { "topic": "Machine Learning Fundamentals", "days": 30 // optional: number of days to spread the plan across (default: 30) } ``` **Response**: ```json { "planId": "uuid", "topic": "Machine Learning Fundamentals", "days": 30, "nodes": [ { "id": "uuid", "title": "Introduction to ML", "description": "Basic concepts and overview", "is_start": true, "next_node_ids": ["uuid2"], "status": "available" } ] } ``` **Days to Sessions**: - 7 days: 3-5 sessions - 14 days: 4-7 sessions - 30 days (default): 5-10 sessions - 60 days: 8-14 sessions - 90 days: 10-18 sessions - 180 days: 15-25 sessions ### 2. Start Session Starts a new Socratic session. **Endpoint**: `POST /api/agent/session/start` **Request**: ```json { "problem": "Explain how gradient descent works in neural networks", "plan_node_id": "uuid-from-plan" // optional, links to plan node } ``` **Response**: ```json { "sessionId": "uuid", "problem": "Explain how gradient descent works...", "nodeTitle": "Gradient Descent", "planId": "uuid", "status": "active", "instructions": { "audioFormat": "webm", "submitEndpoint": "/api/agent/session/analyze", "maxChunkDuration": 60000 } } ``` ### 3. Analyze Audio Chunk Submits an audio chunk for Socratic analysis. Returns reasoning gap score and follow-up questions. **Endpoint**: `POST /api/agent/session/analyze` **Request**: ```json { "session_id": "uuid-from-start", "audio_base64": "base64-encoded-audio-data", "audio_format": "webm" } ``` **Response**: ```json { "sessionId": "uuid", "gapScore": 0.7, "signals": [ "Missing consideration of local minima", "No mention of learning rate impact" ], "transcript": "transcribed audio...", "followUpQuestion": "What happens when the gradient becomes very small?", "requiresFollowUp": true } ``` ### 4. End Session Ends an agent session and generates a summary report. **Endpoint**: `POST /api/agent/session/end` **Request**: ```json { "session_id": "uuid-from-start" } ``` **Response**: ```json { "success": true, "sessionId": "uuid", "message": "Session ended and report generated", "chunkCount": 5, "wordCount": 1200 } ``` ### 5. Get Session Summary Retrieves the summary report of a completed session. **Endpoint**: `GET /api/agent/session/summary?session_id=xxx` **Response (if ready)**: ```json { "ready": true, "sessionId": "uuid", "report": "# Session Report\n\n## Overview\n...", "createdAt": "2026-02-24T12:00:00Z", "status": "completed" } ``` **Response (if not ready)**: ```json { "ready": false, "message": "Session report not ready yet. Call /session/end first to generate the report.", "sessionId": "uuid", "status": "active" } ``` ## Complete Agent Workflow ```python import base64 import requests [REDACTED_SECRET]" BASE_URL = "https://openlesson.academy" HEADERS = {"Authorization": f"Bearer {API_KEY}"} # Step 1: Generate a learning plan (optional: specify days) plan_response = requests.post( f"{BASE_URL}/api/agent/plan", json={ "topic": "Quantum Computing", "days": 14 # optional: number of days for the plan }, headers=HEADERS ) plan = plan_response.json() # Step 2: Start a session for the first node first_node = next(n for n in plan["nodes"] if n["is_start"]) session_response = requests.post( f"{BASE_URL}/api/agent/session/start", json={"plan_node_id": first_node["id"], "problem": first_node["title"]}, headers=HEADERS ) session = session_response.json() # Step 3: Record and analyze audio # 1. Record audio from user (use browser MediaRecorder or similar) # 2. Convert to base64 with open("audio.webm", "rb") as f: audio_base64 = base64.b64encode(f.read()).decode() analyze_response = requests.post( f"{BASE_URL}/api/agent/session/analyze", json={ "session_id": session["sessionId"], "audio_base64": audio_base64, "audio_format": "webm" }, headers=HEADERS ) analysis = analyze_response.json() print(f"Gap Score: {analysis['gapScore']}") print(f"Follow-up: {analysis['followUpQuestion']}") ``` ## Error Handling - **401**: Invalid or inactive API key - **403**: Session doesn't belong to this key or wrong endpoint - **404**: Session not found - **500**: Internal server error ## Tips for Agents 1. **Always use audio**: The analyze endpoint ONLY accepts audio. Never send text. 2. **Record in webm format**: This is the preferred format (Opus codec) 3. **Chunk audio**: Send 30-60 second chunks for analysis 4. **Follow up**: If `requiresFollowUp` is true, ask the follow-up question and record response 5. **Track gap scores**: Use gap score to determine when user has mastered a concept 6. **Use bash -c for curl**: When running API calls in shell scripts, use the `bash -c 'printf "..." | curl ... --data-binary @-'` pattern to avoid JSON escaping issues 7. **Schedule all sessions**: When you generate a learning plan, it is important to schedule all the sessions suggested in the plan for your human. Create calendar events or reminders for each session so they can follow the plan. **Always remind your human when a session is due** - don't wait for them to ask.

path: requires.env
content: OPENLESSON_API_KEY=required:The API key for openLesson Academy. Generate from dashboard at /dashboard

Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (MEDIUM)