Get Started with Skill Management

This guide walks you through creating and using a skill with Langfuse. If you're looking to understand what skill management is and why it matters, check out the Skill Management Overview first. For details on how skills are structured in Langfuse and how it works in the background, see Core Concepts.

Agentic installation

Install the Langfuse Agent Skill to let your coding agent access all Langfuse features.

Ask your coding agent to install the skill by pointing to the GitHub repository and instruct it to get started with Skill Management.

Agent instruction

Install the Langfuse Agent Skill from github.com/langfuse/skills
and use it to create and publish a skill for this application
with Langfuse.

Langfuse has a Cursor Plugin that includes the skill automatically.

Install Plugin in Cursor

Then prompt your agent:

Agent instruction

Create and publish a skill for this application with Langfuse.

Install via npm (skills CLI):

npx skills add langfuse/skills --skill "langfuse"

If you want to target a specific agent directly:

npx skills add langfuse/skills --skill "langfuse" --agent "<agent-id>"

Alternatively you can manually clone the skill

Clone repo somewhere stable

git clone https://github.com/langfuse/skills.git /path/to/langfuse-skills

Make sure your agent's skills dir exists

mkdir -p /path/to/<agent-skill-root>/skills

Symlink the skill folder

ln -s /path/to/langfuse-skills/skills/langfuse /path/to/<agent-skill-root>/skills/langfuse

Then prompt your agent:

Agent instruction

Create and publish a skill for this application with Langfuse.

Manual installation

This guide helps you get started with Langfuse Skill Management manually.

Get API keys

Create Langfuse account or self-host Langfuse.
Create new API credentials in the project settings.

For the CLI and API examples, export your project credentials and Langfuse URL:

export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://cloud.langfuse.com"

Create a skill

If Skills is not visible, enable Skill Management under account menu → Feature Preview. Enable V4 Preview first if its toggle is disabled.

Open Skills → New skill → Create from scratch.
Add your instructions to SKILL.md, including the required name and description frontmatter.
Click Publish, then confirm with Create skill.
Open Labels on the saved version, select production, and click Save and promote to production.

Install the CLI:

npm install -g @langfuse/cli
mkdir -p skill_name

Save your skill locally, for example as skill_name/SKILL.md. Publish the folder and assign production:

langfuse skills push ./skill_name --label production

The command prints the saved version. See version control for API publishing and label management.

Create a version from SKILL.md and assign the production label:

from langfuse import Langfuse
from langfuse.api.skills import SkillVersionFileInput

langfuse = Langfuse()
skill = langfuse.api.skills.create_version(files=[
    SkillVersionFileInput(path="SKILL.md", content="""---
name: skill_name
description: Describe when to use this skill.
---
Instructions for the agent.
"""),
])
langfuse.api.skills.set_labels(skill.name, skill.version, labels=["production"])

Create a version from SKILL.md and assign the production label:

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();
const skill = await langfuse.api.skills.createVersion({
  files: [{
    path: "SKILL.md",
    content: `---
name: skill_name
description: Describe when to use this skill.
---
Instructions for the agent.
`,
  }],
});
await langfuse.api.skills.setLabels(skill.name, skill.version, {
  labels: ["production"],
});

Send SKILL.md to create a version:

curl --request POST "$LANGFUSE_BASE_URL/api/public/skills" \
  --user "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "files": [{
      "path": "SKILL.md",
      "content": "---\nname: skill_name\ndescription: Describe when to use this skill.\n---\nInstructions for the agent."
    }]
  }'

Set SKILL_VERSION to the response's version, then assign production so the loading examples below can retrieve it:

curl --request PATCH \
  "$LANGFUSE_BASE_URL/api/public/skills/skill_name/versions/$SKILL_VERSION" \
  --user "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{"labels":["production"]}'

See the Skills API reference for request and response fields.

Use your skill

Install skill folders for an agent that reads files from disk, or fetch file contents with an SDK or the REST API. Pass the fetched instructions and supporting files to your agent's skill loader.

Install with the CLI

Install the CLI, then download the version labeled production:

npm install -g @langfuse/cli
langfuse skills install skill_name --label production

The CLI writes files to .agents/skills/skill_name/ by default. Configure your agent to read that directory. Installation alone does not make the model use the skill.

In the UI, Use skill → Install with CLI → Configure install command builds a command for one skill, a tag, or all project skills. Choose a label or version and an installation directory, then copy the command or setup prompt for your coding agent.

To pin a version or install a group of skills:

langfuse skills install skill_name --version 2
langfuse skills install --tag tag

Keep the langfuse-skills.lock file reported by the CLI to restore the resolved versions. The CLI looks for it in the installation directory, then the working directory. See the CLI reference for directory and lockfile options.

Restore or update

langfuse skills install
langfuse skills update

install without arguments restores locked versions. update updates already locked skills to the versions assigned to their saved labels; exact version pins stay fixed. Run install --tag tag or install --all again to include newly added skills.

Fetch with the Python SDK

Fetch the version labeled production with its file contents:

from langfuse import Langfuse

langfuse = Langfuse()
skill = langfuse.api.skills.get(
    "skill_name", label="production", include_content=True,
)
instructions = next(file.content for file in skill.files if file.path == "SKILL.md")
if instructions is None:
    raise ValueError("Skill instructions were not returned")
print(instructions)

Each entry in skill.files includes a path and content. Use the same response to read supporting files from this version.

Fetch with the JavaScript/TypeScript SDK

Fetch the version labeled production with its file contents:

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();
const skill = await langfuse.api.skills.get("skill_name", {
  label: "production",
  includeContent: true,
});
const instructions = skill.files.find((file) => file.path === "SKILL.md")?.content;
if (instructions === undefined) throw new Error("Skill instructions were not returned");
console.log(instructions);

Each entry in skill.files includes a path and content. Use the same response to read supporting files from this version.

Fetch through the API

Fetch the version labeled production with its file contents:

curl --get "$LANGFUSE_BASE_URL/api/public/skills/skill_name" \
  --user "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  --data-urlencode "label=production" \
  --data-urlencode "includeContent=true"

The response includes the skill's name, version, and files. Each file has a path, sha256Hash, and content. Read SKILL.md for the instructions and other files as your agent needs them. See the Skills API reference for request and response fields.

Fetch files on demand

Resolve the version

Omit includeContent to fetch a manifest without file contents:

curl --get "$LANGFUSE_BASE_URL/api/public/skills/skill_name" \
  --user "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  --data-urlencode "label=production"

Read a file

Set SKILL_FILE_HASH to a file's sha256Hash from the manifest. Use --data-urlencode to encode the base64 hash correctly:

curl --get "$LANGFUSE_BASE_URL/api/public/skills/files/content" \
  --user "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  --data-urlencode "sha256Hashes=$SKILL_FILE_HASH"

The response's data array contains { sha256Hash, content } objects. Match results to manifest files by hash. Send up to 50 unique hashes as a comma-separated sha256Hashes value to fetch several files. Cache content by hash to reuse it across requests.

For SDK and API requests, pass version instead of label to select a fixed version. Omitting both selects production. Keep the resolved version fixed during a run so instructions and supporting files come from the same revision.

Not seeing what you expected?

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

Next steps

Now that you've created and loaded your first skill, here are a few things we recommend next to make the most of Langfuse Skill Management:

Was this page helpful?

On this page