---
title: Get Started
sidebarTitle: Get Started
seoTitle: Get Started with Skill Management
description: Create a versioned agent skill and load it with the CLI, Python SDK, JavaScript/TypeScript SDK, or REST API.
---

# 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](/docs/skill-management/overview) first. For details on how skills are structured in Langfuse and how it works in the background, see [Core Concepts](/docs/prompt-and-skill-management/concepts).

**Start with Langfuse** [Sign up](/cloud)

h2]:mt-6 [&>h2]:mb-4">

## Agentic installation [#agentic-installation]

Install the [Langfuse Agent Skill](https://github.com/langfuse/skills) to let your coding agent access all Langfuse features.

**Ask your coding agent**

Ask your coding agent to install the skill by pointing to the [GitHub repository](https://github.com/langfuse/skills) and instruct it to get started with Skill Management.

```txt filename="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.
```

**Cursor plugin**

Langfuse has a [Cursor Plugin](https://cursor.com/docs/plugins) that includes the skill automatically.

  [Install Plugin in Cursor](https://cursor.com/marketplace/langfuse)

Then prompt your agent:

```txt filename="Agent instruction"
Create and publish a skill for this application with Langfuse.
```

**Manual installation**

Install via npm ([skills CLI](https://www.npmjs.com/package/skills)):

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

If you want to target a specific agent directly:

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

<Details>
<Summary>Alternatively you can manually clone the skill</Summary>

1. Clone repo somewhere stable

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

2. Make sure your agent's skills dir exists

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

3. Symlink the skill folder

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

</Details>

Then prompt your agent:

```txt filename="Agent instruction"
Create and publish a skill for this application with Langfuse.
```

## Manual installation [#manual-installation]

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

<Steps>

### Get API keys [#get-api-keys]

1.  [Create Langfuse account](https://langfuse.com/cloud) or [self-host Langfuse](/self-hosting).
2.  Create new API credentials in the project settings.

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

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

### Create a skill [#create-a-skill]

**UI**

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

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

![The skill editor showing files, version history, and labels.](/images/changelog/2026-11-03-skill-management-editor.png)

**CLI**

Install the CLI:

```bash
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`:

```bash
langfuse skills push ./skill_name --label production
```

The command prints the saved version. See [version control](/docs/skill-management/version-control) for API publishing and label management.

**Python SDK**

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

```python
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"])
```

**JS/TS SDK**

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

```typescript
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"],
});
```

**API**

Send `SKILL.md` to create a version:

```bash
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:

```bash
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](https://api.reference.langfuse.com/#tag/skills) for request and response fields.

### Use your skill [#load-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.

**CLI**

#### Install with the CLI [#cli-install]

Install the CLI, then download the version labeled `production`:

```bash
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:

```bash
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](https://github.com/langfuse/langfuse-cli#readme) for directory and lockfile options.

##### Restore or update [#restore-or-update]

```bash
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.

**Python SDK**

#### Fetch with the Python SDK [#python-sdk]

Fetch the version labeled `production` with its file contents:

```python
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.

**JS/TS SDK**

#### Fetch with the JavaScript/TypeScript SDK [#javascript-sdk]

Fetch the version labeled `production` with its file contents:

```typescript
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.

**API**

#### Fetch through the API [#api-fetch]

Fetch the version labeled `production` with its file contents:

```bash
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](https://api.reference.langfuse.com/#tag/skills) for request and response fields.

<Details>
<Summary>Fetch files on demand</Summary>

##### Resolve the version [#resolve-the-version]

Omit `includeContent` to fetch a manifest without file contents:

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

##### Read a file [#read-a-file]

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

```bash
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.

</Details>

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.

</Steps>

## Not seeing what you expected?

- [What are the Skill Management limits and how do I troubleshoot issues?](/faq/all/skill-management-limits-and-troubleshooting)

[Ask another question](/docs/ask-ai)

## Next steps [#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:

- [Publish a revision and promote it with labels](/docs/skill-management/version-control).
- [Trace available skills and loaded files](/docs/skill-management/tracing).
- [Troubleshoot missing skills or failed uploads](/faq/all/skill-management-limits-and-troubleshooting).

<!-- agent-instructions -->

---

## 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/docs/skill-management/get-started.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**: <https://langfuse.com/llms.txt>, 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 <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.