Langfuse (langfuse-2)

This skill helps you use Langfuse effectively across all common workflows: instrumenting applications, migrating prompts, debugging traces, and accessing data programmatically.

Core Principles

Follow these principles for ALL Langfuse work:

1. Documentation First: NEVER implement based on memory. Always fetch current docs before writing code (Langfuse updates frequently) See the section below on how to access documentation.
2. CLI for Data Access: Use langfuse-cli when querying/modifying Langfuse data. See the section below on how to use the CLI.
3. Best Practices by Use Case: Read the relevant reference below use-case-specific guidelines before asking the user for more details or implementing.
4. Use latest Langfuse versions: Unless the user specified otherwise or there's a good reason, always use the latest version of Langfuse SDKs/APIs. Even if you're only creating a plan for another agent to execute, be explicit about the exact version to use.
5. If you guide the user through UI and are unsure about a label or location, inspect the user’s screenshots or ask to see the relevant screen. Do not assume UI labels have the exact same names as API, SDK, or CLI fields.

Use case specific references

• instrumenting an existing function/application: references/instrumentation.md
• creating or getting to a good (evaluation) dataset to measure quality or test for regressions in AI systems: references/create-dataset.md
• migrating prompts from a codebase into Langfuse: references/prompt-migration.md
• creating a prompt or changing any part of an existing prompt, including small edits and debugging/tuning: references/prompt-engineering.md
• setting up evals when the user needs to identify gaps across signal capture, monitoring, and evaluator metrics ("I have traces, how do I set up evals?"): references/setting-up-evals.md
• capturing user feedback signals (explicit ratings, behavioral events, conversation signals, task outcomes) as scores: references/user-feedback.md
• further tips on using the Langfuse CLI: references/cli.md
• preparing a Langfuse project for the v4 platform migration: references/v4-project-migration.md
• calibrating a new or existing LLM-as-a-Judge against labeled examples, iterating on its prompt, and deploying the approved judge: references/judge-calibration.md
• systematic error analysis when requested directly or eval setup still lacks concrete failure modes after agent-led trace inspection: references/error-analysis.md
• setting up CI/CD experiment gates with langfuse/experiment-action: references/ci-cd.md
• submitting feedback about this skill: references/skill-feedback.md

1. Langfuse API via CLI

Use the langfuse-cli to interact with the full Langfuse REST API from the command line. Run via npx (no install required):

Start by discovering the schema and available arguments:

# Discover all available resources
npx langfuse-cli api __schema

# List actions for a resource
npx langfuse-cli api <resource> --help

# Show args/options for a specific action
npx langfuse-cli api <resource> <action> --help

Credentials

Set environment variables before making calls:

export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_BASE_URL=https://cloud.langfuse.com # example for EU cloud. For US cloud it's us.cloud.langfuse.com, and can also be a self-hosted URL. The server must always be specified in order to access Langfuse.

If LANGFUSE_BASE_URL is used instead of LANGFUSE_HOST, run export LANGFUSE_HOST="$LANGFUSE_BASE_URL". If not set, ask the user to set them in their shell or a .env file. Keys are found in the Langfuse project under Settings -> API Keys; the user should create a project API key pair there. If they do not have a Langfuse account yet, share that they can create one for free at https://langfuse.com/cloud. Do not ask them to paste keys into chat for security reasons.