Installed skill is missing references/v4-project-migration.md

[aadesh-ingle]

Describe your idea or feedback

The canonical v4 migration prompt circulated with the Langfuse v4 launch instructs the agent:

"If the Langfuse skill is installed, use it and read references/v4-project-migration.md. Otherwise, fetch and follow the canonical migration workflow: https://raw.githubusercontent.com/langfuse/skills/main/skills/langfuse/references/v4-project-migration.md"

Following that with the currently published skill fails at the first branch. The installed skill's references/ directory contains:

cli.md  instrumentation.md  prompt-migration.md
sdk-upgrade.md  skill-feedback.md  user-feedback.md

There is no v4-project-migration.md. SKILL.md's "Use case specific references" list also has no entry for v4 migration, so an agent asked to "migrate this repo to Langfuse v4" has no route to the workflow from inside the skill — it would most likely fall back to sdk-upgrade.md, which is a different and much narrower task.

The prompt's fallback URL works, so the migration still completed. But it only works because the prompt supplies the URL. An agent invoking the skill on its own would never reach the workflow.

Second, smaller point. The skill's "Documentation First" rule sent me to api/search-docs to check which SDK methods survive v3 → v4. It reported get_trace_url as removed in v4. That is incorrect — get_trace_url is present in the v4.14.4 SDK source at langfuse/_client/client.py:2421, alongside auth_check, flush, create_prompt, get_prompt, get_current_trace_id and start_as_current_observation. The search summary appears to infer removal from the method's absence in the migration guide.

Acting on that answer would have meant removing a working call and replacing it with something else, for no reason. I only caught it by fetching the tagged SDK source and grepping.

What would the ideal outcome look like?

1. Ship references/v4-project-migration.md with the skill, and add a v4-migration entry to the "Use case specific references" list in SKILL.md, so the workflow is reachable without an externally supplied URL.

2. Add a verification rule to the workflow (and ideally to SKILL.md's core principles): before removing or replacing an SDK method on the strength of a documentation summary, confirm against the tagged SDK source. Absence from a migration guide is not evidence of removal, and a docs-search answer that says "removed" can be confidently wrong.