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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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`. Set only that encoded credential as\n`LANGFUSE_BASIC_AUTH` through browser admin at\n`/admin/secrets`; if browser admin is unavailable,\nuse `/secret set LANGFUSE_BASIC_AUTH \"<base64-public-colon-secret>\"` in\nbrowser `/chat` or TUI; local console fallback:\n`hybridclaw 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"}]
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:
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.
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. For secrets, use this
order:
Browser admin: open the active HybridClaw admin URL ending in /admin/secrets.
Browser /chat or TUI fallback.
Local console fallback.
LANGFUSE_BASIC_AUTH — base64 of public-key:secret-key:
/secret set LANGFUSE_BASIC_AUTH "<base64-public-colon-secret>"
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 console fallback: hybridclaw secret set LANGFUSE_BASIC_AUTH "<...>"
and hybridclaw env set LANGFUSE_HOST https://cloud.langfuse.com.
Documentation first: never implement from memory. Langfuse updates
frequently — fetch current docs (section 2) before writing instrumentation or
SDK code.
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.
Best practices by use case: check the relevant reference below before
implementing.
Use latest Langfuse versions: unless the user says otherwise, target the
latest Langfuse SDKs/APIs.
1. Langfuse data access (HybridClaw gateway helper)
langfuse.cjs is the API wrapper. Do not handcraft Langfuse API URLs, JSON
bodies, tiers, host, or the Basic auth header from memory.
node skills/langfuse/langfuse.cjs --help
plan classifies a natural-language request into an operation + tier:
node skills/langfuse/langfuse.cjs --format json plan "average eval score this week"
run executes a live request through the gateway (the gateway injects the
Basic auth header):
node skills/langfuse/langfuse.cjs --format json run list-traces --user-id alice --limit 50
http-request emits the gateway-ready payload without calling Langfuse —
use it for dry-run inspection or runtimes without helper gateway access.
Read examples (green):
node skills/langfuse/langfuse.cjs --format json run get-trace --trace-id abc123
node skills/langfuse/langfuse.cjs --format json run list-observations --type GENERATION --trace-id abc123
node skills/langfuse/langfuse.cjs --format json run list-scores --name quality
node skills/langfuse/langfuse.cjs --format json run get-prompt --prompt-name support-reply --label production
node skills/langfuse/langfuse.cjs --format json run metrics --query '{"view":"traces","metrics":[{"measure":"count","aggregation":"count"}]}'
Guarded write examples (amber — only after an explicit operator grant):
node skills/langfuse/langfuse.cjs --format json run create-score \
--trace-id abc123 --name quality --value 0.8 --data-type NUMERIC --comment "reviewed" --operator-grant
node skills/langfuse/langfuse.cjs --format json run create-prompt \
--name summarizer --type text --prompt "Summarize: {{input}}" --label production --operator-grant
Select region or self-hosted host explicitly (otherwise <env:LANGFUSE_HOST>):
node skills/langfuse/langfuse.cjs --format json run list-traces --host https://us.cloud.langfuse.com
Working rules
Reads are green. Writes (create-score, create-comment, create-dataset,
create-dataset-item, create-prompt) require --operator-grant: produce a
plan, wait for the operator's grant, then run the exact approved command.
Deletions and project / API-key / organization / SCIM administration are out
of scope. Use the Langfuse UI for those.
Page size is capped at 100; use --page (legacy) or --cursor (modern
endpoints) to paginate. The helper rejects --limit above 100.
For broad trace queries that time out on Langfuse Cloud, prefer
list-observations (with --trace-id when traversing from a known trace).
In OpenTelemetry-instrumented apps, trace-level input/output can be null —
the content lives in a GENERATION observation, so read observations to see
prompts/outputs.
Before creating a score config, list existing ones (list-score-configs);
configs cannot be deleted.
Never print, inspect, or ask for LANGFUSE_BASIC_AUTH; the gateway injects it
as Authorization: Basic <secret:LANGFUSE_BASIC_AUTH>.
Cost per assistant run is recorded by HybridClaw UsageTotals; helper output
includes costMeasurement.system = "UsageTotals" for eval verification.
2. Langfuse documentation
Prefer your application's native web fetch/search tools (e.g. web_fetch,
web_search) over curl. The URLs work with any fetching method.
2a. Documentation index (llms.txt)
Fetch the full index of doc pages, then fetch the right one:
curl -s https://langfuse.com/llms.txt
2b. Fetch individual pages as markdown
Append .md to any doc path (or send Accept: text/markdown):
The fixture at evals/scenarios.json contains 10 scenarios covering trace,
observation, session, score, metric, prompt, and dataset reads plus guarded
score, dataset, and prompt writes.
Skill feedback
If the skill gives wrong or outdated guidance, is missing something, or could be
improved, offer to submit feedback to the Langfuse skill maintainers following
references/skill-feedback.md. Do not trigger
this for issues with Langfuse the product — only this skill's instructions.
Attribution
Adapted from the official Langfuse skill
(github.com/langfuse/skills), MIT-licensed,
with HybridClaw gateway/SecretRef data access in place of the upstream
langfuse-cli + plaintext-key path. See NOTICE.md.
