quiver-cli 0.8.0 → 1.1.0

package/template/.agents/skills/integrations/langfuse/references/error-analysis.md

@@ -8,6 +8,9 @@ description: Deep-dive error analysis of an LLM pipeline or AI application using
   errors", "build a failure taxonomy", "what's going wrong with my pipeline", or any
   request to systematically inspect, annotate, or score Langfuse traces. If the user
   is trying to understand or improve the quality of an AI system's outputs, use this skill.
+metadata:
+  required_access:
+    - LANGFUSE_PROJECT_INTERFACE
 ---
 
 # Error Analysis
@@ -24,43 +27,28 @@ Read it in full. It defines the authoritative 5-step process (sample selection
 
 **2. Guide the user through this step by step**
 
-You as a coding agent and the user go through this together to perform a full error analysis with their data in langfuse. Do everything you can achieve via CLI (look up traces, create annotation queues, ...) for the user. Provide them with direct links to UI wherever their action is required. Be proactive and narrate what is going on for the user. 
+You as a coding agent and the user go through this together to perform a full error analysis with their data in langfuse. Do as much of the work as you can directly for the user (look up traces, create annotation queues, ...). Provide them with direct links to UI wherever their action is required. Be proactive and narrate what is going on for the user. 
 
 ## Rules CRITICAL
-Use Langfuse CLI wherever possible
+Perform interactions with the user's Langfuse instance yourself rather than telling the user to do them — don't say "now do this in Langfuse" when you can do it directly
+But don't barrel through on assumptions: where a step needs the user's judgment or input (e.g. what to fix, how to label, which evaluator), pause and ask before acting
 Use charts where possible to display data
 
 ---
 
 ## Langfuse Implementation Notes
 
-The guide describes the process. These notes cover the Langfuse-specific API and CLI mechanics required to execute it.
+The guide describes the process. These notes cover the Langfuse-specific mechanics required to execute it.
 
 ### Credentials
 
-```bash
-echo $LANGFUSE_PUBLIC_KEY   # pk-lf-...
-echo $LANGFUSE_SECRET_KEY   # sk-lf-...
-echo $LANGFUSE_BASE_URL     # https://cloud.langfuse.com (EU), https://us.cloud.langfuse.com (US), https://jp.cloud.langfuse.com (JP) or self-hosted
-```
+Make sure Langfuse credentials are available before starting — a public key (`pk-lf-...`), a secret key (`sk-lf-...`), and the host (e.g. `https://cloud.langfuse.com` for EU, `https://us.cloud.langfuse.com` for US, `https://jp.cloud.langfuse.com` for JP, or a self-hosted URL). If they aren't configured, ask the user to set them — do not ask them to paste secret values into chat.
 
-If not set, check `.env` in the project root: `export $(grep -v '^#' .env | xargs)`. If `LANGFUSE_HOST` is used instead of `LANGFUSE_BASE_URL`, run `export LANGFUSE_BASE_URL="$LANGFUSE_HOST"`.
-
-```bash
-AUTH=$(echo -n "${LANGFUSE_PUBLIC_KEY}:${LANGFUSE_SECRET_KEY}" | base64)
-
-# Verify before proceeding
-STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
-  -H "Authorization: Basic $AUTH" \
-  "${LANGFUSE_BASE_URL}/api/public/projects")
-echo "Auth check: $STATUS"
-```
-
-If status is not `200`, stop and ask the user to check their credentials and host before continuing.
+Verify you can actually reach the user's project before proceeding. If access fails, stop and ask the user to check their credentials and host.
 
 ### Annotation target: OBSERVATION versus TRACE
 
-> **CRITICAL:** In OpenTelemetry-instrumented apps, trace-level `input`/`output` can be null — content often lives in a GENERATION observation. Always consider if the right objectType to add is `objectType: OBSERVATION` pointing to the GENERATION observation ID to annotation queues. 
+> **CRITICAL:** In OpenTelemetry-instrumented apps, trace-level `input`/`output` can be null — content often lives in a GENERATION observation. In that case, add the GENERATION observation (not the trace) to the annotation queue, so the content being reviewed is actually visible.
 
 ### Annotation queues
 
@@ -86,15 +74,15 @@ When a category warrants a prompt fix, always offer the user two options:
 
 ### Setup evaluators
 
-When a category warrants an evaluator setup, propose the type of evaluator and offer to set it up for user via CLI
+When a category warrants an evaluator setup, propose the type of evaluator and offer to set it up for the user
 
 
 ### Common gotchas
 
 | Mistake | Fix |
 |---------|-----|
-| `objectType: TRACE` in queue | Use `objectType: OBSERVATION` with GENERATION obs ID |
-| Creating score config without checking existing | `GET /api/public/score-configs` first; can't delete |
+| Annotating the trace instead of the observation | Target the GENERATION observation, not the trace, when content lives there |
+| Creating a score config without checking existing ones | Check existing score configs first; they can't be deleted |
 | Queue created before score configs | Create configs → collect IDs → create queue |
-| `--limit` > 100 on traces list | API hard cap; paginate with `--page` |
-| No rate limiting on queue item creation | `sleep 0.4` between calls to avoid 429 |
+| Requesting too many traces at once | Page size is capped (max 100); paginate to get more |
+| No rate limiting on bulk queue item creation | Space out requests to avoid hitting rate limits (429) |

package/template/.agents/skills/integrations/langfuse/references/instrumentation.md

@@ -1,6 +1,10 @@
 ---
 name: langfuse-observability
 description: Instrument LLM applications with Langfuse tracing. Use when setting up Langfuse, adding observability to LLM calls, or auditing existing instrumentation.
+metadata:
+  required_access:
+    - CODEBASE
+    - LANGFUSE_PROJECT_SCRIPT
 ---
 
 # Langfuse Observability
@@ -31,7 +35,7 @@ Every trace should have these fundamentals:
 | Token usage               | Are input/output tokens tracked?                                                         | Enables automatic cost calculation                     |
 | Good trace names          | Are names descriptive? (`chat-response`, not `trace-1`)                                  | Makes traces findable and filterable                   |
 | Span hierarchy            | Are multi-step operations nested properly?                                               | Shows which step is slow or failing                    |
-| Correct observation types | Are generations marked as generations?                                                   | Enables model-specific analytics                       |
+| Correct observation types | Are generations marked as generations, and is each other call given its most specific type (`retriever` for a lookup, `agent` for a subagent, etc.) rather than a generic `tool`/`span`? See the [observation types docs](https://langfuse.com/docs/observability/features/observation-types). | Enables model-specific analytics and drives the Agent Graph |
 | Sensitive data masked     | Is PII/confidential data excluded or masked?                                             | Prevents data leakage                                  |
 | Trace input/output        | Does the trace capture meaningful input/output? Is input explicitly set to show only relevant data (e.g., user message), not all function args? | Makes traces readable in the UI and avoids leaking sensitive args |
 
@@ -39,72 +43,46 @@ Framework integrations (OpenAI, LangChain, etc.) handle model name, tokens, and
 
 Docs: https://langfuse.com/docs/tracing
 
-### 3. Explore Traces First
+**Beyond the baseline**, add context relevant to the app. Infer from code where possible; only ask when it's not obvious (e.g. how they judge a good vs. bad response, what they'd filter a dashboard by, which user segments they'd compare). These are not baseline — add only what fits.
 
-Once baseline instrumentation is working, encourage the user to explore their traces in the Langfuse UI before adding more context:
+| If code shows...                                     | Add                 | Why                                                                             |
+| ---------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------- |
+| Conversation history, chat endpoints, message arrays | `session_id`        | Groups conversations — [docs](https://langfuse.com/docs/tracing-features/sessions) |
+| User authentication, `user_id` variables             | `user_id`           | User filtering and cost attribution — [docs](https://langfuse.com/docs/tracing-features/users) |
+| Multiple distinct endpoints/features                 | `feature` tag       | Per-feature analytics — [docs](https://langfuse.com/docs/tracing-features/tags) |
+| Customer/tenant identifiers                          | `customer_tier` tag | Cost/quality breakdown by segment — [docs](https://langfuse.com/docs/tracing-features/tags) |
+| Feedback collection, ratings                         | Feedback score      | Quality filtering and trends — [docs](https://langfuse.com/docs/scores/overview) |
 
-"Your traces are now appearing in Langfuse. Take a look at a few of them—see what data is being captured, what's useful, and what's missing. This will help us decide what additional context to add."
+### 3. Run and Self-Audit the Traces (required)
 
-This helps the user:
+Instrumentation isn't done when the code compiles. This is a loop you own as the agent, it's your responsibility to deliver traces of the highest quality your can produce:
 
-- Understand what they're already getting
-- Form opinions about what's missing
-- Ask better questions about what they need
+**a.** Execute the instrumented path end-to-end so a trace is actually sent.
 
-### 4. Discover Additional Context Needs
+**b.** Fetch the trace(s) you just created from Langfuse. Any method works (`langfuse-cli`, REST API, SDK, MCP); the CLI is usually simplest — see [references/cli.md](references/cli.md).
 
-Determine what additional instrumentation would be valuable. **Infer from code when possible, only ask when unclear.**
+**c.** Audit the trace against the best-practices page. **Always fetch it fresh — never audit from memory, this cannot be skipped** (the guidance changes over time):
 
-**Infer from code:**
+https://langfuse.com/docs/observability/best-practices
 
-| If you see in code...                                | Infer             | Suggest                   |
-| ---------------------------------------------------- | ----------------- | ------------------------- |
-| Conversation history, chat endpoints, message arrays | Multi-turn app    | `session_id`              |
-| User authentication, `user_id` variables             | User-aware app    | `user_id` on traces       |
-| Multiple distinct endpoints/features                 | Multi-feature app | `feature` tag             |
-| Customer/tenant identifiers                          | Multi-tenant app  | `customer_id` or tier tag |
-| Feedback collection, ratings                         | Has user feedback | Capture as scores         |
+Ask yourself, for each observation: is all data that a user might need in the future, to understand exactly what context the agent had when it made decisions, available in Langfuse?
 
-**Only ask when not obvious from code:**
+**d.** Fix every gap you find, then re-run and re-fetch to confirm. Repeat until the trace clears the guidance. Then report what you audited and changed, and link the final trace.
 
-- "How do you know when a response is good vs bad?" → Determines scoring approach
-- "What would you want to filter by in a dashboard?" → Surfaces non-obvious tags
-- "Are there different user segments you'd want to compare?" → Customer tiers, plans, etc.
+### 4. Explore Traces With the User
 
-**Additions and their value:**
+With a clean trace in place, invite the user to explore it in the Langfuse UI:
 
-| Addition            | Why                                         | Docs                                                |
-| ------------------- | ------------------------------------------- | --------------------------------------------------- |
-| `session_id`        | Groups conversations together               | https://langfuse.com/docs/tracing-features/sessions |
-| `user_id`           | Enables user filtering and cost attribution | https://langfuse.com/docs/tracing-features/users    |
-| User feedback score | Enables quality filtering and trends        | https://langfuse.com/docs/scores/overview           |
-| `feature` tag       | Per-feature analytics                       | https://langfuse.com/docs/tracing-features/tags     |
-| `customer_tier` tag | Cost/quality breakdown by segment           | https://langfuse.com/docs/tracing-features/tags     |
+"Your traces are now appearing in Langfuse. Take a look at a few of them—see what data is being captured, what's useful, and what's missing."
 
-These are NOT baseline requirements—only add what's relevant based on inference or user input.
+Point them to the relevant views:
 
-### 5. Guide to UI
+- Traces view: individual requests
+- Sessions view: grouped conversations (if `session_id` added)
+- Dashboard: filtered views using tags
+- Scores: filter by quality metrics
 
-After adding context, point users to relevant UI features:
-
-- Traces view: See individual requests
-- Sessions view: See grouped conversations (if session_id added)
-- Dashboard: Build filtered views using tags
-- Scores: Filter by quality metrics
-
-## Framework Integrations
-
-Prefer these over manual instrumentation:
-
-| Framework     | Integration            | Docs                                                 |
-| ------------- | ---------------------- | ---------------------------------------------------- |
-| OpenAI SDK    | Drop-in replacement    | https://langfuse.com/docs/integrations/openai        |
-| LangChain     | Callback handler       | https://langfuse.com/docs/integrations/langchain     |
-| LlamaIndex    | Callback handler       | https://langfuse.com/docs/integrations/llama-index   |
-| Vercel AI SDK | OpenTelemetry exporter | https://langfuse.com/docs/integrations/vercel-ai-sdk |
-| LiteLLM       | Callback or proxy      | https://langfuse.com/docs/integrations/litellm       |
-
-Full list: https://langfuse.com/docs/integrations
+This helps them understand what they're getting, spot what's missing, and ask better questions about what to add next.
 
 ## Always Explain Why
 
@@ -120,6 +98,15 @@ making it much easier to debug multi-turn interactions.
 Learn more: https://langfuse.com/docs/tracing-features/sessions"
 ```
 
+## Multi-agent systems (subagent dispatch)
+
+When one agent's execution dispatches OTHER agents (coding agents like Claude Code/Codex, research agents, orchestrator/worker architectures), a few extra points on top of the baseline:
+
+- **Type a subagent's own execution as `agent`, not `tool`/`span`.** A bare tool/span for a dispatch hides all of the subagent's internal structure; `agent` lets it show up as its own node in the [Agent Graph](https://langfuse.com/docs/observability/features/agent-graphs).
+- **Don't emit duplicate dispatch + execution nodes.** Emitting both a `tool`-typed "dispatch" span and a separate `agent`-typed observation for the same subagent, as siblings, double-represents one event. Emit only the `agent` observation when you have the subagent's actual execution; keep a bare tool span only as a fallback when you have no visibility into what the subagent did.
+- **Nest recursively.** Nest the subagent's `agent` observation under the `agent` or `span` that orchestrates the dispatch, as a sibling of the `generation` that requested it. Within the subagent, put its generations, tool calls, and nested subagent executions under that subagent's `agent` observation; each tool or nested subagent is a sibling of the generation that requested it, not a child of that generation.
+- **Name subagents distinctly.** Frameworks often default every subagent to the same generic role name, making them indistinguishable in the tree and graph (nodes key on name). Derive a specific name from the subagent's actual task/role when the framework doesn't provide one.
+
 ## Common Mistakes
 
 | Mistake                                        | Problem                                             | Fix                                                                               |

package/template/.agents/skills/integrations/langfuse/references/judge-calibration.md

@@ -1,7 +1,10 @@
 ---
 name: langfuse-judge-calibration
-description: Calibrate and validate LLM-as-a-Judge evaluators against dataset ground truth. Runs the judge prompt as a Langfuse dataset experiment, compares judge outputs with dataset item expected outputs, and reports simple accuracy or advanced confusion-matrix metrics. Use this guide whenever a user asks if their LLM judge is actually useful,
-aligned with human judgment, or safe to trust for monitoring decisions.
+description: Calibrate and validate LLM-as-a-Judge evaluators against dataset ground truth. Runs the judge prompt as a Langfuse dataset experiment, compares judge outputs with dataset item expected outputs, and reports simple accuracy or advanced confusion-matrix metrics. Use this guide whenever a user asks if their LLM judge is actually useful, aligned with human judgment, or safe to trust for monitoring decisions.
+metadata:
+  required_access:
+    - CODEBASE
+    - LANGFUSE_PROJECT_SCRIPT
 ---
 
 # Judge Calibration (LLM-as-a-Judge)

package/template/.agents/skills/integrations/langfuse/references/prompt-engineering.md

@@ -0,0 +1,35 @@
+---
+name: langfuse-prompt-engineering
+description: Write or change prompts in Langfuse or code. Use whenever the user asks to create, edit, rewrite, debug, tune, or otherwise modify a prompt, including a small wording or instruction change. Distinct from prompt-migration and judge-calibration.
+metadata:
+  required_access: []
+---
+
+# Prompt Engineering
+
+## Universal principles
+
+1. **Be specific.** State the required output format, constraints, and, when order matters, numbered steps. Write for someone with minimal context.
+2. **Use labeled sections** for the role, instructions, examples, and context. Use XML tags when they help distinguish rules, data, and variables.
+3. **Give the model a role.** A focused system-prompt sentence can steer tone and behavior.
+4. **Explain why important rules exist** so the model can apply them to adjacent cases.
+
+## Adjusting an existing prompt
+
+1. **Pin down the failure first.** Use concrete misbehaving outputs and name the exact failure mode: wrong format, ignored instruction, wrong tone, hallucination, or another observable error. The task and data show what could fail, not what did fail; do not write a fix before observing the failure.
+2. **Trace the failure to the prompt.** Look for a missing, ambiguous, or conflicting instruction.
+3. **Fix the failure class, not the example.** Generalize the observed mistake into an error class and write the instruction at that level, in your own words. Cover adjacent cases, but do not add definitions, rules, or examples for unobserved problems or encode the failing example itself. If a generalized instruction does not work, report the failure instead of narrowing the rule to that case.
+4. **Preserve existing behavior.** Before changing text, identify what behavior it protects. Avoid contradicting other rules or breaking cases that already work.
+5. **Make the smallest testable edit.** Change one cause per attempt so you can attribute the result. Avoid extra length, emphasis, or all-caps. In Langfuse, save each attempt as a new version or label so you can compare and roll back.
+
+## Model-specific tuning
+
+Identify the target model if you can — tuning differs by model, so when you know which model the prompt runs on, follow that model's own prompting guidance.
+
+| Technique | Standard (GPT) | Reasoning (Claude latest) |
+|-----------|----------------|---------------------------|
+| Instruction density | High, prescriptive | Goal-level; don't micro-manage steps |
+| Reasoning | Add explicit chain-of-thought | Native thinking; "think thoroughly" + tune `effort` |
+| Emphasis language | Strong directives fine | Dial back `MUST`/`CRITICAL` |
+| Output format | Prefilling/scaffolds | Prefill removed (4.6+); structured outputs + "no preamble" |
+| Roles | `developer` > `user` > `assistant` | `system` role + `user`/`assistant` |

package/template/.agents/skills/integrations/langfuse/references/prompt-migration.md

@@ -1,234 +1,79 @@
 ---
 name: langfuse-prompt-migration
 description: Migrate hardcoded prompts to Langfuse for version control and deployment-free iteration. Use when user wants to externalize prompts, move prompts to Langfuse, or set up prompt management.
+metadata:
+  required_access:
+    - CODEBASE
+    - LANGFUSE_PROJECT_SCRIPT
 ---
 
 # Langfuse Prompt Migration
 
-Migrate hardcoded prompts to Langfuse for version control, A/B testing, and deployment-free iteration.
+Migrate hardcoded prompts into Langfuse-managed prompts. The API mechanics (`create_prompt`, `get_prompt`, `.compile()`, linking to traces) are in the docs — fetch them at execution time.
 
 ## Prerequisites
 
-Verify credentials are set before starting. Check existence only — never print the secret key, since the value would land in the agent's context and transcripts:
+Verify credentials exist — check presence only, never print the secret key (its value would land in the agent's context and transcripts):
 
 ```bash
-[ -n "$LANGFUSE_PUBLIC_KEY" ] && echo "LANGFUSE_PUBLIC_KEY: set" || echo "LANGFUSE_PUBLIC_KEY: missing"
-[ -n "$LANGFUSE_SECRET_KEY" ] && echo "LANGFUSE_SECRET_KEY: set" || echo "LANGFUSE_SECRET_KEY: missing"
-[ -n "$LANGFUSE_BASE_URL" ]   && echo "LANGFUSE_BASE_URL: $LANGFUSE_BASE_URL" || echo "LANGFUSE_BASE_URL: missing"
+[ -n "$LANGFUSE_PUBLIC_KEY" ] && echo "public key: set" || echo "public key: missing"
+[ -n "$LANGFUSE_SECRET_KEY" ] && echo "secret key: set" || echo "secret key: missing"
+[ -n "${LANGFUSE_BASE_URL:-${LANGFUSE_HOST:-}}" ] && echo "base url: set" || echo "base url: missing"
 ```
 
-If not set, ask the user to configure them in their shell or a `.env` file. Do not ask them to paste keys into chat.
+Use `LANGFUSE_BASE_URL` for current SDKs. If only `LANGFUSE_HOST` is set, export `LANGFUSE_BASE_URL="$LANGFUSE_HOST"`. If a CLI expects `LANGFUSE_HOST` and only `LANGFUSE_BASE_URL` is set, export `LANGFUSE_HOST="$LANGFUSE_BASE_URL"`.
 
-## Migration Flow
+If credentials or the base URL are missing, ask the user to set them in their shell or a `.env` file. Do not ask them to paste secret keys into chat.
 
-```
-1. Scan codebase for prompts
-2. Analyze templating compatibility
-3. Propose structure (names, subprompts, variables)
-4. User approves
-5. Create prompts in Langfuse
-6. Refactor code to use get_prompt()
-7. Link prompts to traces (if tracing enabled)
-8. Verify application works
-```
-
-## Step 1: Find Prompts and Build an Inventory
-
-Before writing ANY code, make a complete list of every prompt you found. For each one, note:
-
-- Name: descriptive, lowercase, hyphenated (e.g. chat-assistant, email-classifier)
-- Source file: where the prompt text lives
-- Code file to refactor: the Python/JS file that USES the prompt (for asset files like .txt/.yaml/.md, this is the file that reads/loads the asset — NOT the asset file itself)
-- Type: chat (used as a message in a chat API) or text (used as a plain string)
-- Variables: values interpolated into the prompt, converted to {{var}} syntax:
-f-string {var} → {{var}}
-.format(var=...) → {{var}}
-${var} → {{var}}
-String concatenation + var + → {{var}}
-YAML {var} → {{var}}
-- Prompt content: the actual text to upload, with variables converted to {{var}} syntax
-
-Search for these patterns:
+## 1. Inventory every prompt (before writing any code)
 
-| Framework | Look for |
-|-----------|----------|
-| OpenAI | `messages=[{"role": "system", "content": "..."}]` |
-| Anthropic | `system="..."` |
-| LangChain | `ChatPromptTemplate`, `SystemMessage` |
-| Vercel AI | `system: "..."`, `prompt: "..."` |
-| Raw | Multi-line strings near LLM calls |
+For each prompt, record:
 
-## Step 2: Check Templating Compatibility
+- **Name**: lowercase, hyphenated (e.g. `chat-assistant`)
+- **Source file**: where the prompt text lives
+- **Code file to refactor**: the file that USES the prompt. For asset files (`.txt`/`.yaml`/`.md`), this is the file that loads the asset, not the asset itself
+- **Type**: `chat` (message array) or `text` (plain string)
+- **Variables**: values interpolated in, converted to `{{var}}`
+- **Content**: the actual text to upload
 
-**CRITICAL:** Langfuse only supports simple `{{variable}}` substitution. No conditionals, loops, or filters.
+Before choosing `text` or `chat`, fetch and follow [Chat vs Text Prompts](https://langfuse.com/docs/prompt-management/data-model#text-vs-chat-prompts). Do not default unrelated prompt flows to one prompt type.
 
-| Template Feature | Langfuse Native | Action |
-|------------------|-----------------|--------|
-| `{{variable}}` | ✅ | Direct migration |
-| `{var}` / `${var}` | ⚠️ | Convert to `{{var}}` |
-| `{% if %}` / `{% for %}` | ❌ | Move logic to code |
-| `{{ var \| filter }}` | ❌ | Apply filter in code |
+Prompts typically live in OpenAI message arrays, Anthropic system arguments, LangChain prompt templates, Vercel AI system/prompt fields, and raw multi-line strings near LLM calls.
 
-**CRITICAL — Variable syntax:** Langfuse uses DOUBLE curly braces for variables: `{{var}}`. When uploading prompt content, you MUST convert every single-brace `{var}` from the original code to double-brace `{{var}}`. Never upload `{var}` — it must be `{{var}}`.
+## 2. Convert templating and decide structure
 
-### Decision Tree
+**Variable syntax:** Langfuse substitutes only double-brace `{{var}}`. Convert every single-brace form during upload — `{var}`, `${var}`, f-string `{var}`, `.format(var=...)`, and string concatenation all become `{{var}}`. Uploading `{var}` will silently fail to substitute.
 
-```
-Contains {% if %}, {% for %}, or filters?
-├─ No → Direct migration
-└─ Yes → Choose:
-    ├─ Option A (RECOMMENDED): Move logic to code, pass pre-computed values
-    └─ Option B: Store raw template, compile client-side with Jinja2
-        └─ ⚠️ Loses: Playground preview, UI experiments
-```
-
-### Simplifying Complex Templates
+**Complex templates:** Langfuse has no conditionals, loops, or filters. If the code uses them (e.g. Jinja `{% if %}`/`{% for %}`), either pre-compute the value in code and pass a plain `{{variable}}` (recommended), or store the raw template and compile client-side — which loses Playground preview and UI experiments. See https://langfuse.com/docs/prompt-management/features/variables and the [external templating FAQ](https://langfuse.com/faq/all/using-external-templating-libraries).
 
-**Conditionals** → Pre-compute in code:
-```python
-# Instead of {% if user.is_premium %}...{% endif %} in prompt
-# Use {{tier_message}} and compute value in code before compile()
-```
-
-**Loops** → Pre-format in code:
-```python
-# Instead of {% for tool in tools %}...{% endfor %} in prompt
-# Use {{tools_list}} and format the list in code before compile()
-```
+**What to make a variable vs. keep hardcoded:**
 
-For external templating details, fetch: https://langfuse.com/faq/all/using-external-templating-libraries
-
-## Step 3: Propose Structure
-
-### Naming Conventions
-
-| Rule | Example | Bad |
-|------|---------|-----|
-| Lowercase, hyphenated | `chat-assistant` | `ChatAssistant_v2` |
-| Feature-based | `document-summarizer` | `prompt1` |
-| Hierarchical for related | `support/triage` | `supportTriage` |
-| Prefix subprompts with `_` | `_base-personality` | `shared-personality` |
-
-### Identify Subprompts
-
-Extract when:
-- Same text in 2+ prompts
-- Represents distinct component (personality, safety rules, format)
-- Would need to change together
-
-### Variable Extraction
-
-| Make Variable | Keep Hardcoded |
+| Make variable | Keep hardcoded |
 |---------------|----------------|
 | User-specific (`{{user_name}}`) | Output format instructions |
 | Dynamic content (`{{context}}`) | Safety guardrails |
-| Per-request (`{{query}}`) | Persona/personality |
+| Per-request (`{{query}}`) | Persona / personality |
 | Environment-specific (`{{company_name}}`) | Static examples |
 
-## Step 4: Present Plan to User
-
-Format:
-```
-Found N prompts across M files:
-
-src/chat.py:
-  - System prompt (47 lines) → 'chat-assistant'
-
-src/support/triage.py:
-  - Triage prompt (34 lines) → 'support/triage'
-    ⚠️ Contains {% if %} - will simplify
-
-Subprompts to extract:
-  - '_base-personality' - used by: chat-assistant, support/triage
-
-Variables to add:
-  - {{user_name}} - hardcoded in 2 prompts
-
-Proceed?
-```
-
-## Step 5: Create Prompts in Langfuse
-
-Use `langfuse.create_prompt()` with:
-- `name`: Your chosen name
-- `prompt`: Template text (or message array for chat type)
-- `type`: `"text"` or `"chat"`
-- `labels`: `["production"]` (they're already live)
-- `config`: Optional model settings
-
-**Labeling strategy:**
-- `production` → All migrated prompts
-- `staging` → Add later for testing
-- `latest` → Auto-applied by Langfuse
-
-For full API: fetch https://langfuse.com/docs/prompts/get-started
-
-## Step 6: Refactor Code
-
-Replace hardcoded prompts with:
-
-```python
-prompt = langfuse.get_prompt("name", label="production")
-messages = prompt.compile(var1=value1, var2=value2)
-```
-
-**Key points:**
-- Always use `label="production"` (not `latest`) for stability
-- Call `.compile()` to substitute variables
-- For chat prompts, result is message array ready for API
-
-For SDK examples (Python/JS/TS): fetch https://langfuse.com/docs/prompts/get-started
-
-## Step 7: Link Prompts to Traces
-
-If codebase uses Langfuse tracing, link prompts so you can see which version produced each response.
-
-### Detect Existing Tracing
-
-Look for:
-- `@observe()` decorators
-- `langfuse.trace()` calls
-- `from langfuse.openai import openai` (instrumented client)
-
-### Link Methods
-
-| Setup | How to Link |
-|-------|-------------|
-| `@observe()` decorator | `langfuse_context.update_current_observation(prompt=prompt)` |
-| Manual tracing | `trace.generation(prompt=prompt, ...)` |
-| OpenAI integration | `openai.chat.completions.create(..., langfuse_prompt=prompt)` |
-
-### Verify in UI
-
-1. Go to **Traces** → select a trace
-2. Click on **Generation**
-3. Check **Prompt** field shows name and version
+**Naming:** lowercase-hyphenated, feature-based (`document-summarizer`), hierarchical for related prompts (`support/triage`), prefix subprompts with `_` (`_base-personality`).
 
-For tracing details: fetch https://langfuse.com/docs/prompts/get-started#link-with-langfuse-tracing
+Before extracting subprompts, fetch and follow [Prompt Composability](https://langfuse.com/docs/prompt-management/features/composability). Use composition for the reuse and shared-maintenance cases described there, not merely to decompose one coherent prompt flow.
 
-## Step 8: Verify Migration
+## 3. Present the plan, then create and refactor
 
-### Checklist
+When the user explicitly requests a migration and credentials work, treat that request as authorization to create prompts and refactor the call sites. Present the inventory and plan as a progress update, then continue.
 
-- [ ] All prompts created with `production` label
-- [ ] Code fetches with `label="production"`
-- [ ] Variables compile without errors
-- [ ] Subprompts resolve correctly
-- [ ] Application behavior unchanged
-- [ ] Generations show linked prompt in UI (if tracing)
+Ask only when a materially different design choice would change behavior, required credentials are unavailable, or destructive cleanup needs approval. Do not stop merely to confirm names, prompt types, or optional tracing.
 
-### Common Issues
+Then:
 
-| Issue | Solution |
-|-------|----------|
-| `PromptNotFoundError` | Check name spelling |
-| Variables not replaced | Use `{{var}}` not `{var}`, call `.compile()` |
-| Subprompt not resolved | Must exist with same label |
-| Old prompt cached | Restart app |
+- Create the prompts (label migrated prompts `production` — they're already live) and refactor call sites to fetch each prompt from Langfuse and compile its variables in. The SDK calls differ across Python and JS/TS — fetch the current docs: https://langfuse.com/docs/prompt-management/get-started
+- Fetch by the `production` label
+- If the codebase already has Langfuse tracing (decorators, an instrumented client, or manual spans), link prompts so you can see which version produced each response. See https://langfuse.com/docs/prompt-management/features/link-to-traces
 
-## Out of Scope
+## 4. Verify
 
-- Prompt engineering (writing better prompts)
-- Evaluation setup
-- A/B testing workflow
-- Non-LLM string templates
+- All prompts created with the `production` label; code fetches with `label="production"`
+- Variables and subprompts compile without errors
+- Application behavior is unchanged
+- Generations show the linked prompt in the UI (if tracing enabled)

package/template/.agents/skills/integrations/langfuse/references/skill-feedback.md

@@ -1,6 +1,9 @@
 ---
 name: langfuse-skill-feedback
 description: Submit feedback about the Langfuse skill to its maintainers via GitHub Discussions. Use when the user indicates the skill gave incorrect guidance, is missing information, or could be improved.
+metadata:
+  required_access:
+    - GITHUB
 ---
 
 # Skill Feedback