langfuse

name	langfuse
description	Use Langfuse for LLM observability and evaluation and look up Langfuse documentation. In HybridClaw, data access (traces, observations, sessions, scores, prompts, datasets, metrics) goes through the gateway-proxied langfuse.cjs helper with SecretRef auth — reads are green, writes are grant-gated. Documentation retrieval uses langfuse.com llms.txt, markdown pages, and search-docs. Covers instrumentation, prompt migration, error analysis, and LLM-as-a-judge calibration.
user-invocable	true
requires	{"bins":["node"]}
credentials	[{"id":"langfuse-basic-auth","kind":"header","required":true,"secret_ref":{"source":"store","id":"LANGFUSE_BASIC_AUTH"},"scope":"Langfuse public API Authorization Basic header secret for <LANGFUSE_HOST>/api/public","how_to_obtain":"In Langfuse, open Project Settings → API Keys and create a key pair\n(public key `pk-lf-...` and secret key `sk-lf-...`). Locally base64-encode\n`public-key:secret-key` and store only that encoded credential in chat with\n`/secret set LANGFUSE_BASIC_AUTH \"<base64-public-colon-secret>\"`.\nThe same key reads observability data and writes scores, comments,\ndatasets, and prompt versions.\n"}]
config_variables	[{"id":"langfuse-host","env":"LANGFUSE_HOST","required":true,"scope":"Langfuse API base URL used in <LANGFUSE_HOST>/api/public","how_to_obtain":"Use your Langfuse deployment base URL: `https://cloud.langfuse.com` (EU),\n`https://us.cloud.langfuse.com` (US), `https://jp.cloud.langfuse.com` (JP),\nor your self-hosted origin. Store it in chat with\n`/env set LANGFUSE_HOST https://cloud.langfuse.com`.\n"}]
metadata	{"hybridclaw":{"category":"observability","short_description":"Langfuse LLM observability: traces, scores, prompts, datasets, metrics, docs lookup, and guarded evaluation writes.","tags":["langfuse","observability","llm","evaluation","tracing","prompts"],"stakes_tiers":{"green":"[Truncated]","amber":"[Truncated]"},"escalation":{"writes":"confirm-each","route":"f14"},"cost_measurement":{"system":"UsageTotals","sub_limit_key":"langfuse"}}}

Langfuse

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

HybridClaw integration. This is the official Langfuse skill (github.com/langfuse/skills, MIT) adapted for HybridClaw. Two things differ from the upstream skill:

1. Credentials never leave the gateway. Do not export LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY, run npx langfuse-cli, or paste keys anywhere. Store them once in the runtime stores (below); the gateway injects them server-side.
2. Data access goes through langfuse.cjs, not the Langfuse CLI. The helper builds each REST request and sends it through the HybridClaw gateway, which resolves Authorization: Basic <secret:LANGFUSE_BASIC_AUTH> and the <env:LANGFUSE_HOST> base URL. Wherever a reference says to run langfuse-cli or curl -H "Authorization: Basic $AUTH", use the helper instead. Documentation retrieval (section 2) is unchanged.

HybridClaw setup

The helper never sees credentials. Store two values once:

1. LANGFUSE_BASIC_AUTH — base64 of public-key:secret-key: /secret set LANGFUSE_BASIC_AUTH "<base64-public-colon-secret>"
2. LANGFUSE_HOST — your Langfuse base URL: /env set LANGFUSE_HOST https://cloud.langfuse.com (use https://us.cloud.langfuse.com for US, https://jp.cloud.langfuse.com for JP, or your self-hosted origin).

Local-terminal alternative: hybridclaw secret set LANGFUSE_BASIC_AUTH "<...>" and hybridclaw env set LANGFUSE_HOST https://cloud.langfuse.com.

See references/operator-setup.md for key scope, host selection, autonomy defaults, and network-policy notes.

Core Principles

Follow these principles for ALL Langfuse work:

1. Documentation first: never implement from memory. Langfuse updates frequently — fetch current docs (section 2) before writing instrumentation or SDK code.
2. Helper for data access: use langfuse.cjs (gateway + SecretRef) when querying or modifying Langfuse data. It owns endpoints, methods, bodies, stakes tiers, host, and the Basic auth placeholder.