What are the Skill Management limits and how do I troubleshoot issues?

Check these limits before uploading a skill. Your agent framework may have additional file or execution requirements.

Current limits

See the Skill Management limits for file, naming, import, and content-fetch requirements.

I cannot open Skills

Open your account menu → Feature Preview and enable Skill Management. If its toggle is disabled, enable V4 Preview first.

A production skill cannot be found

Check that your API keys belong to the project containing the skill. Then check its labels: publishing through the API assigns latest, but fetching without a selector requests production.

Assign production to a version, publish with langfuse skills push ./refund-policy --label production, or request another label or an exact version.

An upload is rejected

Include a root SKILL.md with valid YAML frontmatter containing name and description. Check the file and path limits. Submit every file the version should contain.

Files are installed but the agent does not use them

Configure your agent to read the installation path printed by the CLI. Check that its framework supports skills, and use the frontmatter description to state when the skill should be loaded.

My installed skill did not update

Run langfuse skills update to fetch the versions currently assigned to saved labels. Exact version pins stay fixed. Moving a label leaves installed files unchanged until you update them.

Use hashes from a manifest fetched with the same project credentials. In REST requests, URL-encode base64 hashes with --data-urlencode so characters such as + are preserved, and send at most 50 hashes per request. Match returned files by hash rather than array position.

Skills are missing from a trace

Check that your Langfuse deployment supports skill tracing, then use the checks for the missing field.

Available skills are missing

Attach the skill list to the generation or tool observation before it ends. Raw OpenTelemetry attributes apply only to the span where you set them.
With preview SDK propagation, record model and tool calls inside the propagation scope.
With preview SDK discovery, check the installation directory and wait for discovery before starting spans. Check that the CLI and SDK use compatible lockfile formats to recover versions.

Loaded files are missing

Attach the available skill list to the file-loading tool observation.
Use a recognized tool name and input that identifies a file from that list.
Record a successful tool call with a non-null output.

See skill tracing for the Available skills and Loaded skill views. If the skill's Usage tab is empty, check its date range and selected version.

Was this page helpful?