running-coach-index

nadavyigal's avatarfrom nadavyigal

Reference catalog for all running coach AI skills, shared TypeScript contracts, safety guardrails, and telemetry conventions. Use when working with any running coach feature to understand data schemas, safety patterns, or integration points.

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026
[Tool Routing and Orchestration]

When & Why to Use This Skill

The running-coach-index skill serves as the central governance and discovery hub for the Run-Smart AI ecosystem. It provides a comprehensive reference catalog of shared TypeScript contracts, safety guardrails, and telemetry conventions, ensuring that all specialized running coach skills operate with consistency, security, and architectural integrity. By centralizing data schemas and integration logic, it enables Claude to accurately discover, validate, and orchestrate complex workflows across multiple AI features.

Use Cases

  • Skill Discovery & Routing: Assisting the AI in identifying and selecting the most appropriate specialized skill (such as plan generation or post-run insights) from the Run-Smart catalog.
  • Contract & Schema Validation: Ensuring all data payloads between AI components and system APIs adhere to standardized TypeScript contracts to prevent runtime errors.
  • Safety & Compliance Enforcement: Implementing mandatory safety protocols and medical disclaimers to ensure the AI provides conservative advice and avoids unauthorized medical diagnoses.
  • System Observability: Standardizing telemetry logging for events like skill invocation and safety flags to facilitate performance monitoring and debugging.
namerunning-coach-index
descriptionReference catalog for all running coach AI skills, shared TypeScript contracts, safety guardrails, and telemetry conventions. Use when working with any running coach feature to understand data schemas, safety patterns, or integration points.
short-descriptionCatalog of AI skills, contracts, telemetry, and guardrails for Run-Smart.

Purpose

Defines the shared conventions, contracts, safety posture, and telemetry used by all Run-Smart AI skills. This index allows Claude to discover available skills and the rules they follow.

When Claude should use this skill

  • Before invoking any Run-Smart skill to understand shared schemas, safety guidance, and telemetry
  • When onboarding a new skill to ensure compliance with common contracts
  • When working with running coach features and need to understand data schemas or safety patterns

Invocation guidance

  1. Load shared references in running-coach-index/references/ (contracts, telemetry, conventions, smoke-tests).
  2. Select the appropriate skill directory based on the user's need (plan generation, adjustment, insights, etc.).
  3. Validate request/response payloads against the schemas in contracts.md and skill-specific schemas.

Shared components

  • Contracts: running-coach-index/references/contracts.md
  • Telemetry: running-coach-index/references/telemetry.md
  • Conventions: running-coach-index/references/conventions.md
  • Smoke tests: running-coach-index/references/smoke-tests.md

Safety & guardrails

  • No medical diagnosis. If pain/dizziness/severe symptoms appear, advise stopping activity and consulting a qualified professional.
  • Prefer conservative adjustments under uncertainty.
  • Emit SafetyFlag objects when thresholds are crossed and log via ai_safety_flag_raised.

Integration points

  • Skills are invoked from chat flows (v0/app/api/chat/route.ts, v0/lib/enhanced-ai-coach.ts), plan generation APIs (v0/app/api/generate-plan/route.ts), background jobs (plan adjustment), and post-run screens.

Telemetry events (standard)

  • ai_skill_invoked
  • ai_plan_generated
  • ai_adjustment_applied
  • ai_insight_created
  • ai_safety_flag_raised
  • ai_user_feedback