--- title: What are the Skill Management limits and how do I troubleshoot issues? seoTitle: Skill Management limits and troubleshooting description: Current file limits, naming rules, and common setup issues for Skill Management. tags: [skill-management] --- # 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 [#limits] See the [Skill Management limits](/docs/skill-management/overview#limits) for file, naming, import, and content-fetch requirements. ## I cannot open Skills [#beta-access] 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 [#missing-label] 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](/docs/skill-management/version-control#labels), publish with `langfuse skills push ./refund-policy --label production`, or request another label or an exact version. ## An upload is rejected [#upload-rejected] Include a root `SKILL.md` with valid YAML frontmatter containing `name` and `description`. Check the [file and path limits](/docs/skill-management/overview#limits). Submit every file the version should contain. ## Files are installed but the agent does not use them [#agent-loading] 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 [#updates] 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. ## File content fetch fails [#content-fetch] 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 [#missing-trace-skills] Check that your Langfuse deployment supports skill tracing, then use the checks for the missing field. ### Available skills are missing [#missing-available-skills] - 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 [#missing-loaded-files] - Attach the available skill list to the file-loading tool observation. - Use a [recognized tool name and input](/docs/skill-management/tracing#skill-loading-tools) that identifies a file from that list. - Record a successful tool call with a non-null output. See [skill tracing](/docs/skill-management/tracing) for the **Available skills** and **Loaded skill** views. If the skill's **Usage** tab is empty, check its date range and selected version. --- ## Agent Instructions This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/faq/all/skill-management-limits-and-troubleshooting.md`. ### Querying these docs If the answer is not on this page, query the documentation instead of guessing: - **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question: ```bash curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?" ``` - **Index of every page**: , with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt). ### Before writing Langfuse code - **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results. - **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application. - **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples. - **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx @langfuse/cli api `) to read or write traces, prompts, datasets, and scores from the terminal. Found an error in these docs? Please open an issue at .