Claude Code Skill

What It Does

The Moda Claude Code skill teaches AI assistants how to correctly integrate Moda’s LLM observability SDK into any TypeScript or Python project. Instead of guessing at configuration, the AI detects your project stack and applies the right integration pattern automatically. The skill handles:

Detecting your framework and LLM provider
Installing the correct SDK (moda-ai for both npm and PyPI)
Placing init() at the right entry point for your framework
Choosing the correct conversation ID strategy
Adding flush() in cleanup hooks
Configuring Vercel AI SDK telemetry

Prerequisites

Claude Code must be installed and available in your terminal
A Moda API key (get one from the Moda dashboard)

Installation

The skill files are available in the Moda GitHub repository. You can install them per-project or globally.

# From your project root
mkdir -p .claude/skills
cp -r path/to/moda-setup/ .claude/skills/moda-setup/

# Available in every Claude Code session
mkdir -p ~/.claude/skills
cp -r path/to/moda-setup/ ~/.claude/skills/moda-setup/

# Clone directly from the Moda repository
git clone https://github.com/modaflows/moda.git /tmp/moda
cp -r /tmp/moda/moda-setup/ .claude/skills/moda-setup/
rm -rf /tmp/moda

Usage

Once installed, the skill activates automatically when you ask Claude Code to:

“Add Moda observability to this project”
“Integrate LLM analytics”
“Set up conversation tracking for my AI calls”
“Add tracing for OpenAI/Anthropic calls”

You can also invoke it directly:

/moda-setup

What It Handles

Framework Detection

The skill inspects your project files to detect:

File	Detects
`package.json`	Node.js framework, AI SDK, LLM provider
`requirements.txt` / `pyproject.toml`	Python framework, LLM provider
`next.config.*`	Next.js
`app/layout.tsx`	Next.js App Router
`instrumentation.ts`	Existing instrumentation setup

Conversation Threading

The skill automatically chooses the right conversation ID strategy:

Pattern	Strategy
Simple chatbot	Auto-detection (hash-based)
Web server	Scoped context per request
Agent framework	Explicit ID (auto doesn’t work with agents)
Multi-agent system	Shared parent task ID

Agent frameworks like LangChain, CrewAI, and AutoGPT require explicit conversation IDs. The automatic fallback does NOT work because each agent iteration constructs different messages.

Correct Placement

The skill knows where to place initialization for each framework:

Framework	`init()` Location	`flush()` Location
Next.js	`instrumentation.ts`	Route handler `waitUntil`
Express	Server startup	`SIGTERM` handler
FastAPI	Lifespan event	Lifespan cleanup
Flask	App factory / module level	`teardown_appcontext`
Generic script	Top of file	Before exit

Supported Frameworks

TypeScript / Node.js

Next.js (App Router + Vercel AI SDK)
Express
Generic Node.js scripts
Vercel AI SDK
OpenAI SDK
Anthropic SDK

Python

FastAPI
Flask
LangChain
CrewAI
Generic Python scripts
OpenAI SDK
Anthropic SDK

Example Session

Here’s what happens when you ask Claude Code to integrate Moda into a Next.js project:

You: Add Moda analytics to this project

Claude: I'll integrate Moda into your Next.js + Vercel AI SDK project.

1. Installing the SDK:
   npm install moda-ai

2. Creating instrumentation.ts for initialization:
   [creates instrumentation.ts with Moda.init()]

3. Updating your route handler:
   [adds Moda.conversationId and experimental_telemetry
    to your existing chat route]

4. Adding MODA_API_KEY to .env.local:
   [adds the environment variable]

Done! Your LLM calls will now be tracked in Moda with automatic
conversation threading. Get your API key from the Moda dashboard
and add it to .env.local.

Python SDK Reference

Full Python SDK documentation

Node.js SDK Reference

Full TypeScript/Node.js SDK documentation

Vercel AI SDK

Vercel AI SDK integration guide

Quick Start

Get started with Moda in 5 minutes

Getting Started

Ingestion

Frameworks

Prompt Management

Harness

Data API

Claude Code Skill

What It Does

Prerequisites

Installation

Usage

What It Handles

Framework Detection

Conversation Threading

Correct Placement

Supported Frameworks

TypeScript / Node.js

Python

Example Session

Python SDK Reference

Node.js SDK Reference

Vercel AI SDK

Quick Start

​What It Does

​Prerequisites

​Installation

​Usage

​What It Handles

​Framework Detection

​Conversation Threading

​Correct Placement

​Supported Frameworks

TypeScript / Node.js

Python

​Example Session

​Related

Python SDK Reference

Node.js SDK Reference

Vercel AI SDK

Quick Start

What It Does

Prerequisites

Installation

Usage

What It Handles

Framework Detection

Conversation Threading

Correct Placement

Supported Frameworks

Example Session

Related