workout-explainer

nadavyigal's avatarfrom nadavyigal

Translates planned workouts into clear execution cues, purpose, mistakes to avoid, and substitutions.

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026
[Tutoring and Explanations]

When & Why to Use This Skill

The workout-explainer skill acts as an intelligent fitness coach by translating complex workout plans into clear, actionable execution cues. It enhances user safety and performance by explaining the intent of each movement, identifying common mistakes to avoid, and providing personalized exercise substitutions based on the user's experience level and physical capabilities.

Use Cases

  • Real-time Form Guidance: Providing concise, beginner-friendly execution cues and purpose descriptions when a user opens a workout detail modal or asks for clarification on a specific exercise.
  • Adaptive Exercise Substitution: Automatically suggesting safe alternatives or easier variations when a programmed workout intensity mismatches the user's current fitness level or equipment availability.
  • Injury Prevention & Safety Guardrails: Monitoring workout intensity and emitting safety flags to prevent overexertion, while offering specific 'mistakes to avoid' to ensure proper technique and long-term health.
nameworkout-explainer
descriptionTranslates planned workouts into clear execution cues, purpose, mistakes to avoid, and substitutions.
short-descriptionExplains workouts with cues, intent, and safe substitutions.

When Codex should use it

  • When the user opens a workout detail modal or asks “how do I do this workout?”
  • During chat if the user needs clarifications or substitutions.

Invocation guidance

  1. Provide the Workout object and user capability context (experience, recent runs).
  2. Return execution cues, purpose, common mistakes, and two substitutions.
  3. Keep guidance concise (<120 words) and beginner-friendly when experience is low.

Input schema

See references/input-schema.json.

Output schema

See references/output-schema.json.

Integration points

  • UI: Workout detail modal and plan screen tooltips.
  • Chat: Served through v0/app/api/chat/route.ts with workout-explainer intent.

Safety & guardrails

  • If workout intensity mismatches user level, propose easier substitution and emit SafetyFlag.
  • No medical advice; advise stopping on pain/dizziness.

Telemetry

  • Emit ai_skill_invoked with workout_type, experience, safety_flags.